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INTRODUCTION 



The "C" programming language is rapidly growing in popularity 
and seems destined to become one of the most popular programming 
languages used for microcomputers. The rapid rise in the use of C 
is not surprising. C is an incredibly versatile and efficient 
language that can handle tasks that previously would have required 
complex assembly language programming. 

C was originally developed at Bell Telephone Laboratories as an 
implementation language for the UNIX operating system by Brian 
Kernighan and Dennis Ritchie. They also wrote a book titled "The C 
Programming Language" which is universally accepted as the standard 
for the language. It is an interesting reflection on the language 
that although no formal industry-wide "standard" was ever developed 
for C, programs written in C tend to be far more portable between 
radically different computer system as compared to so-called 
"standardized" languages such as BASIC, COBOL, and PASCAL. The 
reason C is so portable is that the language is so inherently 
expandable that if some special function is required, the user can 
create a portable extension to the language, as opposed to the 
common practice of adding additional statements to the language. 
For example, the number of special-purpose BASIC dialects defies all 
reason. A lesser factor is the underlying UNIX operating system, 
which is also sufficiently versatile to discourage 
nonstandardization of the language. Indeed, standard C compilers 
and Unix are intimately related. 

Fortunately, the 6809 microprocessor, the 0S-9 operating 
system, and the C language form an outstanding combination. The 
6809 was specifically designed to efficiently run high-level 
languages, and its stack-oriented instruction set and versatile 
repertoire of addressing modes handle the C language very well. As 
mentioned previously, UNIX and C are closely related, and because 
OS-9 is derived from UNIX, it also supports C to the degree that 
almost any application written in C can be transported from a UNIX 
system to an OS-9 system, recompiled, and correctly executed. 
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THE LANGUAGE IMPLEMENTATION 



OS-9 C is implemented almost exactly as described in 'The C 
Programming Language* by Kernighan and Ritchie (hereafter referred 
to as K & R). A copy of this book, which serves as the language 
reference manual, is included with each software package. 

Although this version of C follows the specification faith- 
fully, there are some differences. The differences mostly reflect 
parts of C that are obsolete or the constraints imposed by memory 
size limitations. 



DIFFERENCES FROM THE K & R SPECIFICATION 



- Bit fields are not supported. 

- Constant expressions for initializers may include arithmetic 
operators only if all the operands are of type INT or CHAR. 

- The older forms of assignment operators, '=+' or '=»', which 
are recognized by some C compilers, are not supported. You 
must use the newer forms '+=','»=' etc. 

- "#ifdef (or #ifndef) . . . [#else . . . ] #endif" is supported but 
"#if <constant expression)" is not. 

- It is not possible to extend macro definitions or strings 
over more than one line of source code. 

- The escape sequence for new-line *\n' refers to the ASCII 
carriage return character (used by OS-9 for end-of-line) , not 
linefeed. (hex OA). Programs which use '\n' for end-of-line 
(which includes all programs in K & R), will still work 
properly. 
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ENHANCEMENTS AND EXTENSIONS 



The "Direct" Storage Class 

The 6809 microprocessor instructions for accessing memory via 
an index register or the stack pointer can be relatively short and 
fast when they are used in C programs to access "auto" (function 
local) variables or function arguments. The instructions for 
accessing global variables are normally not so nice and must be four 
bytes long and correspondingly slow. However, the 6809 has a nice 
feature which helps considerably. Memory, anywhere in a single page 
(256 byte block), may be accessed with fast, two byte instructions. 
This is called the "direct page", and at any time its location is 
specified by the contents of the "direct page register" within the 
processor. The linkage editor sorts out where this should be, and 
it need not concern the programmer, who only needs to specify for 
the compiler which variables should be in the direct page to give 
the maximum benefit in code size and execution speed. 

To this end, a new storage class specifier is recognized by the 
compiler. In the manner of K & R page 192, the sc-specifier list 
is extended as follows: 

Sc-specifier: auto 

static 

extern 

register 

typedef 

direct (extension) 

extern direct (extension) 

static direct (extension) 

The new key word may be used in place of one of the other sc- 
specifiers, and its effect is that the variable will be placed in 
the direct page. "DIRECT" creates a global direct page variable. 
"EXTERN DIRECT" references an EXTERNAL- type direct page variable; 
and "STATIC DIRECT" creates a local direct page variable. These new 
classes may not be used to declare function arguments. "Direct" 
variables can be initialized but will, as with other variables not 
explicitly initialized, have the value zero at the start of program 
execution. 255 bytes are available in the direct page (the linker 
requires one byte). If all the direct variables occupy less than the 
full 255 bytes, the remaining global variables will occupy the 
balance and memory above if necessary. If too many bytes of storage 
are requested in the direct page, the linkage editor will report an 
error, and the programmer will have to reduce the use of DIRECT-type 
variables to fit the 256 bytes addressable by the 6809. 

It should be kept in mind that "direct" is unique to this 
compiler, and it may not be possible to transport programs written 
using "direct" to other environments without modification. 
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Imbedded Assembly Language 



As versatile as C Is, occasionally there are some things that 
can only be done (or done at maximum speed) in assembly language. 
The OS-9 C compiler permits user-supplied assembly-language 
statements to be directly embedded in C source programs. 

A line beginning with "#asm" switches the compiler into a mode 
which passes all subsequent lines directly to the assembly-language 
output, until a line beginning with n #endasm" is encountered, 
"tfendasm" switches the mode back to normal. Care should be 
exercised when using this directive so that the correct code section 
is adhered to. Normal code from the compiler is in the PSECT (code) 
section. If your assembly code uses the VSECT (variable) section, 
be sure to put a ENDSECT directive at the end to leave the state 
correct for following compiler generated code. 



Control Character Escape Sequences 

The escape sequences for non-printing characters in character 
constants and strings (see K & R page 181) are extended as follows: 

linefeed (LF): \1 (lower case 'ell') 

This is to distinguish LF (hex OA) from \n which on OS-9 is the same 
as \r (hex OD) . 



bit patterns: \NNN (octal constant) 

\dNNN (decimal constant) 
\xNN (hexadecimal constant) 

For example, the following all have a value of 255 (decimal): 

\377 \xff \d255 
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IMPLEMENTATION DEPENDENT CHARACTERISTICS 

K & R frequently refer to characteristics of the C language 
whose exact operations depend on the architecture and instruction 
set of the computer actually used. This section contains specific 
information regarding this version of C for the 6809 processor. 



Data Representation and Storage Requirements 

Each variable type requires a specific amount of memory for 
storage. The sizes of the basic types in bytes are as follows: 



Data Type 


Siz< 


CHAR 


1 


INT 


2 


UNSIGNED 


2 


LONG 


4 


FLOAT 


H 


DOUBLE 


8 



Internal Representation 

two's complement binary 

two's complement binary 

unsigned binary 

two's complement binary 

binary floating point (see below) 

binary floating point (see below) 



This compiler follows the PDP-11 implementation and format in 
that CHARs are converted to INTs by sign extension, "SHORT" or 
"SHORT INT" means INT, "LONG INT" means LONG, and "LONG FLOAT" means 
DOUBLE. The format for DOUBLE values is as follows: 



(low byte) 

+_+ 

! ! seven byte 
! ! mantissa 



(high byte) 



! 1 byte ! 
! exponent i 

-+ h 



sign bit 



The form of the mantissa is sign and magnitude with an implied 
"1" bit at the sign bit position. The exponent is biased by 128. 
The format of a FLOAT is identical, except that the mantissa is only 
three bytes long. Conversion from DOUBLE to FLOAT is carried out by 
truncating the least significant (right-most) four bytes of the 
mantissa. The reverse conversion is done by padding the least 
significant four mantissa bytes with zeros. 



Register Variables 

One register variable may be declared in each function. The 
only types permitted for register variables are int, unsigned and 
pointer. Invalid register variable declarations are ignored; i.e. 
the storage class is made auto. For further details see K & R page 
81 . 
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A considerable saving in code size and speed can be made by 
judicious use of a register variable. The most efficient use is 
made of it for a pointer or a counter for a loop. However, if a 
register variable is used in a complex arithmetic expression, there 
is no saving. The "U n register is assigned to register variables. 

IMPORTANT NOTE: Upper and lower case letters cannot be mixed as in 

Basie09. For example, Prog.c and prog.c are distinct names. Since 

the Color Computer is usually used in upper case only, it is 

necessary to enter the following commands to use upper AND lower 
case: TMODE -UPC and CLEAR<0>. 



Access To Command Line Parameters 

The standard C arguments "argc" and "argv" are available to 
"main" as described in K & R page 110. The start-up routine for C 
programs ensures that the parameter string passed to it by the 
parent process is converted into null-terminated strings as expected 
by the program. In addition, it will run together as a single 
argument any strings enclosed between single or double quotes ( " '" 
or ' nl ) . If either is part of the string required, then the other 
should be used as a delimiter. 



"c" VARHPLE 
A/AM&S Ate 

ro g c HA-AAC TBRS 

SAM£ F0R C.PR£p 

» daS x-n a o#i y&z no 
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SYSTEM CALLS AND THE STANDARD LIBRARY 



Operating System Calls 

The system interface supports almost all the system calls of 
both OS-9 and UNIX. In order to facilitate the portability of 
programs from UNIX, some of the calls use UNIX names rather than 
OS-9 names for the same function. There are a few UNIX calls that 
do not have exactly equivalent OS-9 calls. In these cases, the 
library function simulates the function of the corresponding UNIX 
call. In eases where there are OS-9 calls that do not have UNIX 
equivalents, the OS-9 names are used. Details of the calls and a 
name cross-reference are provided in the n C System Calls" section of 
this manual. 



The Standard Library 

The C compiler includes a very complete library of standard 
functions. It is essential for any program which uses functions 
from the standard library to have the statement: 

"#include <stdio.h>" 

See the "C Standard Library" section of this manual for details on 
the standard library functions provided. 

IMPORTANT NOTE: If output via printf(), fprintfO or sprintfO of 
long integers is required, the program MUST call "pflinit() n at some 
point; this is necessary so that programs not involving LONGs do not 
have the extra LONGs output code appended. Similarly, if FLOATs or 
DOUBLES are to be printed, "pffinitQ" MUST be called. These func- 
tions do nothing; existence of calls to them in a program informs 
the linker that the relevant routines are also needed. 
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RON-TIME ARITHMETIC ERROR HANDLING 

K & R leave the treatment of various arithmetic errors open, 
merely saying that it is machine dependent. This implementation 
deals with a limited number of error conditions in a special way; it 
should be assumed that the results of other possible errors are 
undefined. 

Three new system error numbers are defined in <errno.h>: 

#define EFPOVR 40 /« floating point overflow or underflow «/ 
#define EDIVERR 41 /» division by zero */ 

#define EINTERR 42 /« overflow on conversion of floating point 

to long integer »/ 

If one of these conditions occur, the program will send a 
signal to itself with the value of one of these errors. If not 
caught or ignored, this will cause termination of the program with 
an error return to the parent process. However, the program can 
catch the interrupt using "signal ()" or "intercept () " (see C System 
Calls), and in this case the service routine has the error number as 
its argument. 



Page 1-8 



MICROWARE C COMPILER USER'S GUIDE 
THE C COMPILER SYSTEM 



ACHIEVING MAXIMUM PROGRAM PERFORMANCE 



Programming Considerations 

Because the 6809 is an 8/16 bit microprocessor, the compiler 
can generate efficient code for 8 and 16 bit objects (CHARs, INTs, 
etc.). However, code for 32 and 64 bit values (LONGs, FLOATS, 
DOUBLES) can be at least four times longer and slower. Therefore 
don't use LONG, FLOAT, or DOUBLE where INT or UNSIGNED will do. 

The compiler can perform extensive evaluation of constant 
expressions provided they involve only constants of type CHAR, INT, 
and UNSIGNED. There is no constant expression evaluation at 
compile-time (except single constants and "casts" of them) where 
there are constants of type LONG, FLOAT, or DOUBLE, therefore, 
complex constant expressions involving these types are evaluated at 
run time by the compiled program. You should manually compute the 
value of constant expressions of these types if speed is essential. 



The Optimizer Pass 

The optimizer pass automatically occurs after the compilation 
passes. It reads the assembler source code text and removes 
redundant code and searches for code sequences that can be replaced 
by shorter and faster equivalents. The optimizer will shorten object 
code by about 11$ with a significant increase in program execution 
speed. The optimizer is recommended for production versions of de- 
bugged programs. Because this pass takes additional time, the "-0" 
compiler option can be used to inhibit it during error-checking-only 
compilations . 



The Profiler 

The profiler is an optional method used to determine the 
frequency of execution of each function in a C program. It allows 
you to identify the most frequently used functions where algorithmic 
or C source code programming improvements will yield the greatest 
gains. 

When the "-P" compiler option is selected, code is generated at 
the beginning of each function to call the profiler module (called 
"_prof"), which counts invocations of each function during program 
execution. When the program has terminated, the profiler 
automatically prints a list of all functions and the number of times 
each was called. The profiler slightly reduces program execution 
speed. See "prof.c" source for more information. 
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C COMPILER COMPONENT FILES AND FILE USAGE 



Compilation of a C program by cc requires that the following 
files be present in the current execution directory (CMDS). 

OS-9 Level I Systems: 

cc1 compiler executive program 

c.prep macro pre-processor 

c.passl compiler pass 1 

c.pass2 compiler pass 2 

c.opt assembly code optimizer 

c.asm relocating assembler 

clink linkage editor 

OS-9 Level II Systems: 

cc2 compiler executive program 

c.prep macro pre-processor 

c.comp compiler proper 

c.opt assembly code optimizer 

c.asm relocating assembler 

clink linkage editor 

In addition a file called "clib.l" contains the standard lib- 
rary, math functions, and system library. The file "cstart.r" is 
the setup code for compiled programs. Both of these files must be 
located in a directory named "LIB" on drive /D1. The DEFS directory 
must also be on /D1. 

If, when specifying "#include" files for the preprocessor to 

read in, the programmer uses angle brackets, "<" and ">", instead of 

parentheses, the file will be sought starting at the "DEFS" 
directory. 



Temporary Files 

A number of temporary files are created in the current data 
directory during compilation, and it is important to ensure that 
enough space is available on the disk drive. As a rough guide, at 
least three times the number of blocks in the largest source file 
(and its included files) should be free. 

The identifiers "etext" , "edata" , and "end" are predefined in the 
linkage editor and may be used to establish the addresses of the end 
of executable text, initialized data, and uninitialized data 
respectively. 
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RUNNING THE COMPILER 



There are two commands which invoke distinct versions of the 
compiler. "ed" is for OS-9 Level I which uses a two pass compiler, 
and, cc2 is for Level II which uses a single pass version. Both 
versions of the compiler work identically, the main difference is 
that cc1 has been divided into two passes to fit the smaller memory 
size of OS-9 Level I systems. In the following text, "cc" refers to 
either "cd" or "cc2" as appropriate for your system. The syntax of 
the command line which calls the compiler is: 



cc [ option-flags ] file {file} 



One file at a time can be compiled, or a number of files may be 
compiled together. The compiler manages the compilation through up 
to four stages: pre-processor , compilation to assembler code, 
assembly to relocatable module, and linking to binary executable 
code (in OS-9 memory module format). 

The compiler accepts three types of source files, provided each 
name on the command line has the relevant postfix as shown below. 
Any of the above file types may be mixed on the command line. 



File Name Suffix Conventions 

Suffix Usage 



. c 

. a 

. r 

none 



C source file 

assembly language source file 

relocatable module 

executable binary (OS-9 memory module) 



s 
th 



There are two modes of operation: multiple source file and 
ingle source file. The compiler selects the mode by inspecting 
he command line. The usual mode is single source and is specified 
_y having only one source file name on the command line. Of 
course, more than one source file may be compiled together by using 
the "//include" facility in the source code. In this mode, the 
compiler will use the name obtained by removing the postfix from the 

ramp einnnl l oii *-.m 4- Vi ^ ^/i *»_.-. «^ -!■,•«« ««,j *-u« «,, *. ~,, +. *• ,• i „ / _ — .0 i_i 



name supplied 



cc prg.c 

will leave an executable file called "prg" in the current execution 
directory. 

The multiple source mode is specified by having more than one 



Page 1-11 



MICHOWARE C COMPILER USER'S GUIDE 
THE C COMPILER SYSTEM 



source file name on the command line. In this mode, the object code 
output file will have the name "output" in the current execution 
directory, unless a name is given using the "-fr" option (see 
below). Also, in multiple source mode, the relocatable modules 
generated as intermediate files will be left in the same directories 
as their corresponding source files with the postfixes changed to 
".r". For example: 

cc prgl.c /d0/fred/prg2.c 



will leave an executable file called "output" in the current 
execution directory, one called "prgl.r" in the current data 
directory, and "prg2.r" in n /dO/fred". 

CC -E=3 PNAME.C -F=PR0G 



compiles the file called "PNAME.C" into an executable object file 
named "PROG" and sets the module revision level to 3. 

CC PROG.C -DIDENTIFIER=VALUE 



compiles the program with a definition identifier being passed to 
the compiler. The definition being passed is used within the source 
to control compilation via IFDEF/IFNDEF functions. 
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COMPILER OPTION FLAGS 



The compiler recognizes several command-line option flags which 
modify the compilation process where needed. All flags are 
recognized before compilation commences so the flags may be placed 
anywhere on the command line. Flags may be ran together as in "- 
ro", except where a flag is followed by something else; see "-f=" 
and "-d" for examples. 



-A suppresses assembly, leaving the output as assembler code in a 
file whose name is postfixed n .a". 

-E=<number> Set the edition number constant byte to the number 
given. This is an OS-9 convention for memory modules. 

-0 inhibits the assembly code optimizer pass. The optimizer will 
shorten object code by about 11$ with a comparable increase in speed 
and is recommended for production versions of de-bugged programs. 

-P invokes the profiler to generate function invocation frequency 
statistics after program execution. 

-R suppresses linking library modules into an executable program. 
Outputs are left in files with postfixes ".r". 

-M=<memory size> will instruct the linker to allocate <memory size> 
for data, stack, and parameter area. Memory size may be expressed 
in pages (an integer) or in kilobytes by appending "k" to an 
integer. For more details of the use of this option, see the 
"Memory Management" section of this manual. 

-L=<filename> specifies a library to be searched by the linker 
before the Standard Library and system interface. 

-F=<path> overrides the above output file naming. The output file 
will be left with <filename> as its name. This flag does not make 
sense in multiple source mode, and either the -a or -r flag is also 
present. The module will be called the last name in <path>. 

-C will output the source code as comments with the assembler code. 

-S stops the generation of stack-checking code. -S should only be 
used with great care when the application is extremely time-critical 
and when the use of the stack by compiler generated code is fully 
understood. 

-D identified is equivalent to "#define <identifier>" written in 
the source file. -D is useful where different versions of a program 
are maintained in one source file and differentiated by means of the 
"#ifdef" or "#ifndef" pre-processor directives. If the <identifier> 
is used as a macro for expansion by the pre-processor, n 1"(one) will 

CCL -X 

cKtAtC 9 Ul 90 ItlT 
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be the expanded "value" unless the form "-d<identif ier>=<string>" is 
used in which ease the expansion will be <string>. 



COMMAND LINE AND OPTION FLAG EXAMPLES 



command line action output file(s) 



cc prg.c compile to an executable prg 

program 

cc prg.c -a compile to assembly prg. a 

language source code 

cc prg.c -r compile to relocatable prg.r 

module 

cc prgl.c prg2.c prg3.c compile to executable prgl.r, prg2.r, 

program prg3.r, output 

cc prgl.c prg2.a prg3.r compile prgl.c, prgl.r, prg2.r 

assemble prg2.a and 
combine all into an 
executable program 

cc prgl.c prg2.c -a compile to assembly prgl.a, prg2.a 

language source code 

cc prgl.c prg2.c -f=prg compile to executable prg 

program 
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The Object Code Module 

The compiler produces position-independent, reentrant 6809 code 
in a standard OS-9 memory module format. The format of an execut- 
able program module is shown below. Detailed descriptions of each 
section of the module are given on following pages. 



Module 
Offset 



$00 

$09 
$0B 
$0D 



Section 
Size (bytes) 



Module Header 



Execution Offset 

Permanent Storage Size 

Module Name 

Executable Code 
String Literals 



v <--+ 



Initializing Data Size 
Initializing Data 



Data-text Reference Count 



Data-text Reference Offsets 



Data-data Reference Count 



Data-data Reference Offsets 



CRC Check Value 
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Module Header 

This is a standard module header with the type/language byte set to 
$11 (Program + 6809 Object Code), and the attribute/revision byte 
set to $81 (Reentrant +1). 



Execution Offset 

Used by OS-9 to locate where to start execution of the program. 

Storage Size 

Storage size is the initial default allocation of memory for data, 
stack, and parameter area. For a full description of memory 
allocation, see the section entitled "Memory Management" located 
elsewhere in this manual. 

Module Name 

Module name is used by OS-9 to enter the module in the module 

directory. The module name is followed by the edition byte encoded 

in cstart. If this situation is not desired it may be overridden by 
the -E= option in cc. 

Information 

Any strings preceded by the directive "info" in an assembly code 
file will be placed here. A major use of this facility is to place 
in the module the version number and/or a copyright notice. Note 
that the '#asm' pre-compiler instruction may be used in a C source 
file to enable the inclusion of this directive in the compiler- 
generated assembly code file. 

Executable Code 

The machine code instructions of the program. 

String Literals 

Quoted strings in the C source are placed here. They are in the 
null-terminated form expected by the functions in the Standard 
Library. NOTE: the definition of the C language assumes that 
strings are in the DATA area and are therefore subject to alteration 
without making the program non-reentrant. However, in order to avoid 
the duplication of memory requirements which would be necessary if 
they were to be in the data area, they are placed in the TEXT 
(executable) section of the module. Putting the strings in the 
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executable section implies that no attempt should be made by a C 
programmer to alter string literals. They should be copied out 
first. The exception that proves the rule is the initialization of 
an array of type char like this: 

char message[] = "Hello world\n"; 

The string will be found in the array 'message' in the data area and 
can be altered. 



Initializing Data and its Size 

If a C program contains initializers, the data for the initial 
values of the variables is placed in this section. The definition 
of C states that all uninitialized global and static variables have 
the value zero when the program starts running, so the startup 
routine of each C program first copies the data from the module into 
the data area and then clears the rest of the data memory to nulls. 



Data References 

No absolute addresses are known at compile time under OS-9, so where 
there are pointer values in the initializing data, they must be 
adjusted at run time so that they reflect the absolute values at 
that time. The startup routine uses the two data reference tables 
to locate the values that need alteration and adjusts them by the 
absolute values of the bases of the executable code and data re- 
spectively . 

For example, suppose there are the following statements in the 
program being compiled: 

char *p = "I'm a string!"; 
char **q = &p; 

These declarations tell the compiler that there is to be a char 
pointer variable, 'p', whose initial value is the address of the 
string and a pointer to a char pointer, 'q', whose initial value is 
the address of 'p'. The variables must be in the DATA section of 
memory at run time because they are potentially alterable, but 
absolute addresses are not known until run time, so the values that 
'p' and 'q' must have are not known at compile time. The string 
will be placed by the compiler in the TEXT section and will not be 
copied out to DATA memory by the startup routine. The initializing 
data section of the program module will contain entries for 'p' and 
'q'. They will have as values the offsets of the string from the 
base of the TEXT section and the offset of the location of 'p' from 
the base of the DATA section respectively. 

The startup routine will first copy all the entries in the initial- 
izing data section into their allotted places in the DATA section. 
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Then it will scan the data-text reference table for the offsets of 
values that need to have the addresses of the base of the TEXR 
section added to them. Among these will be "p n which, after 
updating, will point to the string which is in the TEXT section. 
Similarly, after a scan of the data-data references, "q" will point 
to(contain the absolute of) "p". 



MEMORY MANAGEMENT 



The C compiler and its support programs have default conditions 
such that the average programmer need not be concerned with details 
of memory management. However, there are situations, where advanced 
programmers may wish to tailor the storage allocation of a program 
for special situations. The following information explains in 
detail how a C program's data area is allocated and used. 



Typical C Program Memory Map 

A storage area is allocated by OS-9 when the C program is executed. 
The layout of this memory is as follows: 

high addresses 
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The overall size of this memory area is defined by the "storage 
size" value stored in the program's module header. This can be 
overridden to assign the program additional memory if the OS-9 Shell 
"#" command is used. 

The parameter area is where the parameter string from the 
calling process (typically the OS-9 Shell) is placed by the system. 
The initializing routine for C programs converts the parameters into 
null-terminated strings and makes pointers to them available to 
'main()' via ' argc ' and ' argv ' . 

The stack area is the currently reserved memory for exclusive 
use of the stack. As each C function is entered, a routine in the 
system interface is called to reserve enough stack space for the use 
of the function with an addition of 64 bytes. The 64 bytes are for 
the use of user-written assembly code functions and/or the system 
interface and/or arithmetic routines. A record is kept of the 
lowest address so far granted for the stack. If the area requested 
would not bring this lower then the C function is allowed to 
proceed. If the new lower limit would mean that the stack area 
would overlap the data area, the program stops with the message: 

•««« STACK OVERFLOW **** 

on the standard error output. Otherwise, the new lower limit is 
set, and the C function resumes as before. 

The direct page variables area is where variables reside 
that have been defined with the storage class 'direct' in the C 
source code or in the 'direct' segment in assembly code source. 
Notice that the size of this area is always at least one byte (to 
ensure that no pointer to a variable can have the value NULL or 0) 
and that it is not necessarily 256 bytes. 

The uninitialized data area is where the remainder of the 
uninitialized program variables reside. These two areas are, in 
fact, cleared to all zeros by the program entry routine. The 
initialized data area is where the initialized variables of the 
program reside. There are two globally defined values which may be 
referred to: 'edata' and 'end', which are the addresses of one byte 
higher than the initialized data and one byte higher than the 
uninitialized data respectively. Note that these are not variables; 
the values are accessed in C by using the '&' operator as in: 

high = &end; 
low = Sedata; 

and in assembler: 

leax end,y 
stx high,y 

The Y register points to the base of the data area and variables are 
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addresses using Y-offset indexed instructions. 

When the program starts running, the remaining memory is 
assigned to the "free" area. A program may call n ibrk()" to 
request additional working memory (initialized to zeros) from the 
free memory area. Alternatively, more memory can be dynamically 
obtained using the n sbrk()" which requests additional memory from 
the operating system and returns its lower bound. If this fails 
because OS-9 refuses to grant more memory for any reason "sbrkO" 
will return -1 . 

Compile Time Memory Allocation 

If not instructed otherwise, the linker will automatically 
allocate 1k bytes more than the total size of the program's 
variables and strings. This size will normally be adequate to cover 
the parameter area, stack requirements, and Standard Library file 
buffers. The allocation size may be altered when using the compiler 
by using the "-m" option on the command line. The memory 
requirements may be stated in pages, for example, 

cc prg.c -m=2 

which allocates 512 bytes extra, or in kilobytes, for example: 

cc prg.c -m=10k. 

The linker will ignore the request if the size is less than 256 
bytes . 



The following rules can serve as a rough guide to estimate how 
much memory to specify: 

1 . The parameter area should be large enough for any anticipated 
command line string. 

2. The stack should be not less than 128 bytes and should take 
into account the depth of function calling chains and any 
recursion. 

3. All function arguments and local variables occupy stack space 
and each function entered needs 4 bytes more for the return 
address and temporary storage of the calling function's register 
variable. 

4. Free memory is requested by the Standard Library I/O 
functions for buffers at the rate of 256 bytes per accessed 
file. This does not apply to the lower level service request I/O 
functions such as "open()», "readO" or "writeO" nor to 
"stderr" which is always un-buffered, but it does apply to both 
"stdin" and "stdouf (see the Standard Library documentation). 
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A good method for getting a feel for how much memory is 
needed by your program is to allow the linker to set the memory size 
to its usually conservative default value. Then, if the program runs 
with a variety of input satisfactorily but memory is limited on the 
system, try reducing the allocation at the next compilation. If a 
stack overflow occurs or an "ibrk() n call returns -1, then try 
increasing the memory next time. You cannot damage the system by 
getting it wrong, but data may be lost if the program runs out of 
space at a crucial time. It pays to be in error on the generous 
side. 
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INTRODUCTION TO C SYSTEM CALLS 



This section of the C compiler manual is a guide to the system 
calls available from C programs. 

It is NOT intended as a definitive description of OS-9 service 
requests as these are described in the OS-9 SYSTEM PROGRAMMER'S 
MANUAL. However, for most calls, enough information is available 
here to enable the programmer to write system calls into programs 
without looking further. 

The names used for the system calls are chosen so that programs 
transported from other machines or operating systems should compile 
and run with as little modification as possible. However, care 
should be taken as the parameters and returned values of some calls 
may not be compatible with those on other systems. Programmers that 
are already familiar with OS-9 names and values should take 
particular care. Some calls do not share the same names as the OS-9 
assembly language equivalents. The assembly language equivalent 
call is shown, where there is one, on the relevant page of the C 
call description, and a cross-reference list is provided for those 
already familiar with OS-9 calls. 

The normal error indication on return from a system call is a 
returned value of -1 . The relevant error will be found in the pre- 
defined int "errno". Errno always contains the error from the last 
erroneous system call. Definitions for the errors for inclusion in 
the program are in "<errno.h>". 

In the "SEE ALSO" sections on the following pages, unless 
otherwise stated, the references are to other system calls. 

Where "#include" files are shown, it is not mandatory to 

include them, but it might be convenient to use the manifest 

constants defined in them rather than integers; it certainly makes 
for more readable programs. 
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Abort - stop the program and produce a core dump 

USAGE 

abort( ) 

DESCRIPTION 

This call causes a memory image to be written out to the file 
"core" in the current directory, and then the program exits 
with a status of 1 . 
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Abs - Absolute value 

USAGE 

int abs(i) 
int i ; 

DESCRIPTION 

ABS returns absolute value of its integer operand. 
CAVEATS 

You get what the hardware gives on the largest negative number. 
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Access - give file accessibility 
USAGE 



access ( fname , perm) 
char «name; 
int perm; 



DESCRIPTION 



Access returns if the access modes specified in "perm" are 
correct for the user to access "fname". -1 is returned if the 
file cannot be accessed. 

The value for "perm" may be any legal OS-9 mode as used for 
"openO" or "creatO", it may be zero, which tests whether the 
file exists, or the path to it may be searched. 



CAVEATS 



NOTE that the "perm" value is NOT compatible with other 
systems . 



DIAGNOSTICS 



The appropriate error indication, if a value of -1 is returned, 
may be found in "errno". 
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Chain - load and execute a new program 

DSAGE 

chain (mod name , paramsize, par amp tr , type , lang, datasize ) 
char *modname, *paramptr ; 

ASSEMBLER EQUIVALENT 

os9 F$CHAIN 

DESCRIPTION 

The action of F$CHAIN is described fully in the OS-9 
documentation. Chain implements the service request as 
described with one important exception: chain will NEVER return 
to the caller. If there is an error, the process will abort 
and return to its parent process. It might be wise, therefore, 
for the program to check the existence and access permissions 
of the module before calling chain. Permissions may be checked 
by using "modlink() n or "modload( ) " followed by an "munlink( ) " . 

"Modname" should point to the name of the desired module. 
"Paramsize" is the length of the parameter string (which should 
normally be terminated with a "\n"), and "paramptr" points to 
the parameter string. "Type" is the module type as found in 
the module header (normally 1: program), and "lang" should 
match the language nibble in the module header (C programs 
have 1 for 6809 machine code here). "Datasize" may be zero, or 
it may contain the number of 256 byte pages to give to the new 
process as initial allocation of data memory. 
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Chdir,Chxdir - change directory 
USAGE 

chdir (dirname) 
char *dirname; 

chxdir (dirname) 
char «dirname; 

ASSEMBLER EQUIVALENT 

os9 I$CHGDIR 

DESCRIPTION 

These calls change the current data directory and the current 
execution directory, respectively, for the running task. 
"Dirname" is a pointer to a string that gives a pathname for a 
directory. 

DIAGNOSTICS 

Each call returns after a successful call, or -1 if "dirname" 
is not a directory path name, or it is not searchable. 

SEE ALSO 

OS-9 shell commands "chd" and "chx". 
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Chmod - change access permissions of a file 



USAGE 



#include <modes.h> 

chmod( f name , perm) 
ehar *fname; 



DESCRIPTION 



Chmod changes the permission bits associated with a file. 
"Fname" must be a pointer to a file name, and "perm" should 
contain the desired bit pattern. 



/* owner read */ 

/* owner write */ 

/* owner execute */ 

/* public read «/ 

/* public write «/ 

/* public execute •/ 

/* sharable */ 

/* directory */ 

Only the owner or the super user may change the permissions of 
a file. 



The allowable bit patt 


erns are d< 


sf ine 


follows: 






/* permissions */ 




#define 


S_IREAD 


0x01 


//define 


S_IWRITE 


0x02 


#define 


S_EXEC 


0x04 


#define 


S_IOREAD 


0x08 


#define 


S_IOWRITE 


0x10 


//define 


S_IOEXEC 


0x20 


//define 


S_ISHARE 


0x40 


//define 


S_IFDIR 


0x80 



DIAGNOSTICS 

A successful call returns NULL(0). A -1 is returned if the 
caller is not entitled to change permissions or "fname" cannot 
be found. 

SEE ALSO 

OS-9 command "attr" 
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Chown - change the ownership of a file 
USAGE 



chown ( fname , owner id) 
char *fname; 



DESCRIPTION 



This call is available only to the super user. "Fname" is a 
pointer to a file name, and "ownerid" is the new user-id. 



DIAGNOSTICS 



Zero is returned from a successful call. -1 is returned on 
error. 
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Close - close a file 
USAGE 

close(pn) 
ASSEMBLER EQUIVALENT 

os9 I$CLOSE 

DESCRIPTION 

Close takes a path number, "pn", as returned from system calls 
"open() n , "creat() n , or "dup() n , and closes the associated 
file. 

Termination of a task always closes all open files 
automatically, but it is necessary to close files where 
multiple files are opened by the task, and it is desired to 
re-use path numbers to avoid going over the system or process 
path number limit. 

SEE ALSO 

creat() ,open() ,dup( ) . 
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Crc - compute a cyclic redundancy count 
OSAGE 

crc ( start , count , accum) 
char *start,accum[3] ; 

ASSEMBLER EQUIVALENT 

os9 F$CRC 

DESCRIPTION 

This call accumulates a crc into a three byte array at "accum" 
for "count" bytes starting at "start". All three bytes of 
"accum" should be initialized to Oxff before the first call to 
"crc() n . However, repeated calls can be subsequently made to 
cover an entire module. If the result is to be used as an OS-9 
module crc, it should have its bytes complemented before 
insertion at the end of the module. 
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Creat - create a new file 



USAGE 



^include <modes.h> 

creat( f name, perm) 
char *fname; 

ASSEMBLER EQUIVALENT 

os9 I$CREATE 

DESCRIPTION 

Creat returns a path number to a new file available for 
writing, giving it the permissions specified in "perm" and 
making the task user the owner. If, however, "fname" is the 
name of an existing file, the file is truncated to zero length, 
and the ownership and permissions remain unchanged. NOTE, 
that unlike the OS-9 assembler service request, creat does 
not return an error if the file already exists. "Access() n 
should be used to establish the existence of a file if it is 
important that a file should not be overwritten. 

It is unnecessary to specify writing permissions in "perm" in 
order to write to the file in the current task. 

The permissions allowed are defined in the include file as 



follows: 

/« 
#define 
//define 
#define 
#define 
//define 
//define 
//define 
#define 



permissions */ 
S_IPRM Oxff 
S_IREAD 0x01 
S_IWRITE 0x02 
S_IEXEC 0x04 
S_I0READ 0x08 
S_I0WRITE 0x10 
S_I0EXEC 0x20 
S_ISHARE 0x40 



/* mask for permission bits */ 

/* owner read »/ 

/* owner write */ 

/* owner execute */ 

/* public read */ 

/* public write */ 

/* public execute */ 

/* sharable */ 



Directories 
instead . 



may not be created with this call; use "mknod() n 



DIAGNOSTICS 



This call returns -1 if there are too many files open. If the 
pathname cannot be searched, if permission to write is denied, 
or if the file exists and is a directory. 



SEE ALSO 



write () , close () ,chmod( ) 
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Defdrive - get default system drive 



USAGE 



char «defdrive() 

DESCRIPTION 

A call to defdrive returns a pointer to a string containing the 
name of the default system drive. The method used is to 
the "Init" module for the default directory name. 



consult 
name is 
returned 

DIAGNOSTICS 



The 
copied to a static data area and a pointer to it is 



-1 is returned if the "Init" module cannot be linked to. 
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Dup - duplicate an open path number 
OSAGE 

dup(pn) 
ASSEMBLER EQUIVALENT 

os9 I$DUP 
DESCRIPTION 



Dup takes the path number, "pn", as returned from n open()" or 
"creat() n and returns another path number associated with the 
same file. 

DIAGNOSTICS 

A -1 is returned if the call fails because there are too many 
files open or the path number is invalid. 

SEE ALSO 

open() , creat() ,close() 
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Exit,_Exit - task termination 
USAGE 

exit(status) 

_exit ( status) 
ASSEMBLER EQUIVALENT 

osg F$EXIT 
DESCRIPTION 

Exit is the normal means of terminating a task. Exit does any 
cleaning up operations required before terminating, such as 
flushing out any file buffers (see Standard I/o), but _exit 
does not. 

A task finishing normally, that is returning from n main() n , 
is equivalent to a call - "exit(0) n . 

The status passed to exit is available to the parent task if it 
is executing a "wait". 

SEE ALSO 

wait( ) 
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Getpid - get the task Id 



USAGE 

getpid( ) 
ASSEMBLER EQUIVALENT 

os9 F$ID 

DESCRIPTION 

A number unique to the current running task is often useful in 
creating names for temporary files. This call returns the 
task's system id (as returned to its parent by "os9fork"). 

SEE ALSO 

,si 5 

os9fork() Standard Library function mktemp. 
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Getstat - get file status 
USAGE 

//include <sgstat.h> 

getstat(code,filenum, buffer) /« code «/ 

char *buffer; 

getstat(code,filenum) /» codes 1 and 6 */ 

getstat(code,filenum,size) /* code 2 */ 
long *size; 

getstat(code,filenum,pos) /» code 5 */ 
long *pos; 

ASSEMBLER EQUIVALENT 

os9 I$GETSTT 

DESCRIPTION 

A full description of getstat can be found in the OS-9 System 
Programmer's Manual. 

"Code" must be the value of one of the standard codes for the 
getstat service request. "filenum" must be the path number of 
an open file. 

The form of the call depends on the value of "code". 

Code 0: "Buffer" must be the address of a 32 byte 

buffer into which the relevant status packet 
is copied. The header file has the 
definitions of the various file and device 
structures for use by the program. 

Code 1 : Code 1 only applies to SCF devices and to 

test for data available. The return value is 
zero if there is data available. -1 is 
returned if there is no data. 

Code 2 "Size" should be the address of a long 

integer into which the current file size is 
placed. The return value of the function is 
-1 on error and on success. 

Code 5 "Pos" should be the address of a long integer 
into which the current file size is placed. 
The return value of the function is -1 on 
error and on success. 

Code 6 Returns -1 on EOF and error and on success. 
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NOTE that when one of the previous calls returns -1 , the 
actual error is returned in errno. 
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Getuid - return U3er id 
USAGE 

getuidO 
ASSEMBLER EQUIVALENT 

os9 F$ID 
DESCRIPTION 

Getuid returns the real user id of the current task (as 
maintained in the password file). 
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Intercept - set function for interrupt processing 

USAGE 

intercept ( func) 

int (*func)(); /* i.e. "func" is a pointer to a function 

returning an int */ 

ASSEMBLER EQUIVALENT 

F$ICPT 

DESCRIPTION 

Intercept instructs OS-9 to pass control to the function "func" 
when an interrupt ( signal) is received by the current process. 

If the interrupt processing function has an argument, it will 
contain the value of the signal received. On return from 
"func", the process resumes at the point in the program where 
it was interrupted by the signal. "Interrupt () " is an 
alternative to the use of "signal()" to process interrupts. 

As an example, suppose we wish to ensure that a partially 
completed output file is deleted if an interrupt is received. 
The body of the program might include: 

char »temp_file = "temp"; /* name of temporary file •/ 
int pn = 0; /* path number */ 

int intrupt(); /* predeclaration »/ 



intercept(intrupt) ; /» route interrupt processing */ 
pn = creat ( temp_f ile, 3) ; /* make a new file */ 



write(pn, string, count) /* write string to temp file */ 



close ( pn) ; 
pn=0; 
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The interrupt routine might be coded: 

intrupt(sig) ; 
{ 

if (pn){ /* only done if pn refers to an open file */ 
close( pn) ; 

unlink( temp_file) ; /* delete •/ 
} 
exit(sig) ; 
} 



CAVEATS 



"InterceptO" and "signalO" are mutually incompatible so that 
calls to both must not appear in the same program. The linker 
guards against this by giving an "entry name clash - _sigint" 
error if it is attempted. 



SEE ALSO 

signal( ) 
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Kill - send an interrupt to a task 
OSAGE 



#include <signal.h> 
kill( tid , interrupt ) 

DESCRIPTION 

Kill sends the interrupt type "interrupt" to the task with id 
"tid". 

Both tasks, sender and receiver, must have the same user id 
unless the user is the super user. 

The include file contains definitions of the defined signals as 
follows: 

/* OS-9 signals */ 
#define SIGKILL /• system abort (cannot be caught or 

ignored )»/ 
#define SIGWAKE 1 /« wake up »/ 
#define SIGQUIT 2 /* keyboard abort «/ 
#define SIGINT 3 /• keyboard interrupt «/ 

Other user-defined signals may, of course, be sent. 

DIAGNOSTICS 

Kill returns from a successful call and -1 if the task does 
not exist, the effective user ids do not match, or the user is 
not the system manager. 

SEE ALSO 

signal() OS-9 shell command "kill" 
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Lseek - position in file 
USAGE 

long lseek(pn, position, type) 
long position; 

ASSEMBLER EQUIVALENT 

os9 I$SEEK 

DESCRIPTION 

The read or write pointer for the open file with the path 
number, "pn", is positioned by lseek to the specified place in 
the file. The "type" indicates from where "position" is to be 
measured: if 0, from the beginning of the file, if 1, from the 
current location, or if 2, from the end of the file. 

Seeking to a location beyond the end of a file open for 
writing and then writing to it, creates a "hole" in the file 
which appears to be filled with zeros from the previous end to 
the position sought. 

The returned value is the resulting position in the file unless 
there is an error, so to find out the current position use 

lseek(pn,0l,1 ) ; 

CAVEATS 

The argument "position" MUST be a long integer. Constants 
should be explicitly made long by appending an "1", as above, 
and other types should be converted using a cast; 

e.g. lseek(pn,(long)pos, 1 ) ; 

Notice also, that the return value from lseek is itself a long 
integer. 

DIAGNOSTICS 

-1 is returned if "pn" is a bad path number, or attempting to 
seek to a position before the beginning of a file. 

SEE ALSO 

open() , creat() Standard Library function "fseek" 



Page 3-22 



MICROWARE C COMPILER USER'S GUIDE 
C SYSTEM CALLS 



Mknod - create a directory 
USAGE 

#include <modes.h> 

mknod (f name, d esc) 
char »fname; 

ASSEMBLER EQUIVALENT 

osg I$MAKDIR 

DESCRIPTION 

This call may be used to create a new directory. "Fname" 
should point to a string containing the desired name of the 
directory. "Deso" is a descriptor specifying the desired mode 
(file type) and permissions of the new file. 

The include file defines the possible values for "desc" as 
follows: 

/* owner read */ 

/* owner write */ 

/* owner execute */ 

/* public read */ 

/* public write «/ 

/* public execute »/ 

/* sharable «/ 

DIAGNOSTICS 

Zero is returned if the directory has been successfully made; - 
1 if the file already exists. 

SEE ALSO 

OS-9 command "makdir" 



#define 


S_IREAD 


0x01 


//define 


S_IWRITE 


0x02 


//define 


S_IEXEC 


0x04 


//define 


S_IOREAD 


0x08 


//define 


S_IOWRITE 


0x10 


//define 


S_IOEXEC 


0x20 


//define 


S_ISHARE 


0x40 
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Modload, Modlink - return a pointer to a module structure 

USAGE 

#include <module.h> 

mod_exec *modlink(modname, type , language) 

char »modname; 

mod_exec «modload( filename , type , language) 
char "filename; 

ASSEMBLER EQUIVALENT 

os9 F$LINK 

os9 F$LOAD 

DESCRIPTION 

Each of these calls return a pointer to an OS-9 memory module. 

Modlink will search the module directory for a module with the 
same name as "modname" and, if found, increment its link count. 

Modload will open the file which has the path list specified by 
"filename" and loads modules from the file adding them to the 
module directory. The returned value is a pointer to the first 
module loaded. 

Above, each is shown as returning a pointer to an executable 
module, but it will return a pointer to whatever type of module 
is found. 

DIAGNOSTICS 

-1 is returned on error. 
SEE ALSO 

munlink( ) 
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Munlink - unlink a module 
USAGE 

//include <module.h> 
munlink(mod) 
mod_exec *mod; 

ASSEMBLER EQUIVALENT 

osg F$UNLINK 

DESCRIPTION 

This call informs the system that the module pointed to by 
"mod" is no longer required by the current process. Its link 
count is decremented, and the module is removed from the module 
directory if the link count reaches zero. 

SEE ALSO 

modlink( ) ,modload( ) 
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_os9 - system call interface from C programs 

USAGE 

^include <os9.h> 

_os9( code , reg) 

char code; 

struct registers *reg; 

DESCRIPTION 

_os9 enables a programmer to access virtually any OS-9 system 
call directly from a C program without having to resort to 
assembly language routines. 

Code is one of the codes that are defined in os9.h. os9.h 
contains codes for the F$ and 1$ function/service requests, and 
it also contains getstt, setstt, and error codes. 

The input registers( reg) for the system calls are accessed by 
the following structure that is defined in os9.h: 

struct registers { 

char rg_cc,rg_a,rg_b,rg_dup; 
unsigned rg_x,rg_y , rg_u ; 

}; 

An example program that uses _os9 is presented on the following 
page. 

DIAGNOSTICS 

-1 is returned if the OS-9 call failed. is returned on 
success . 
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Program example: 



//include <os9.h> 
#include <modes.h> 

/* this program does an I$GETSTT call to get file size */ 

main( argc , argv) 

int argc; 

char *»argv; 

{ 

struct registers reg; 

int path; 

/* tell linker we need longs */ 
pflinit( ) ; 

/* low level open(file name is first command line param »/ 
path=open(»++argv, S_IREAD) ; 

/* set up regs for call to OS-9 »/ 
reg.rg_a=path; 
reg.rg_b=SS_SIZE; 

if(_os9(I_GETSTT,&reg) == 0) 

printf ( "filesize = %1x\n n , /* success */ 

(long) (reg.rg_x << 1 6 )+reg.rg_u) ; 
else printf ("0S9 error #?d\n" ,reg. rg_b & Oxff); /"failed*/ 



} 



dumpregs(&reg) ; /» take a look at the registers »/ 



dumpregs(r ) 

register struct registers *r; 

{ 

printf("cc=?02x\n",r->rg_cc & Oxff); 

printf (" a=$02x\n",r->rg_a & Oxff); 

printfC b=?02x\n",r->rg_b & Oxff); 

printf ( n dp=$02x\n",r->rg_dp & Oxff); 

printf(" x = jt04x\n" ,r->rg x) ; 

printf(" y=$04x\n",r->rg_y) ; 

printfC u=?04x\n",r->rg_u); 
} 
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Open - open a file for read/write access 

USAGE 

open( fname ,mode) 
char *fname; 

ASSEMBLER EQUIVALENT 

os9 I$OPEN 

DESCRIPTION 

This call opens an existing file for reading if "mode" is 1 , 
writing if "mode" is 2, or reading and writing if "mode" is 3. 
NOTE that these values are OS-9 specific and not compatible 
with other systems. "Fname" should point to a string 
representing the pathname of the file. 

Open returns an integer as "path number" which should be used 
by i/o system calls referring to the file. 

The position where reads or writes start is at the beginning of 
the file. 

DIAGNOSTICS 

-1 is returned if the file does not exist, if the pathname 
cannot be searched, if too many files are already open, or if 
the file permissions deny the requested mode. 

SEE ALSO 

Creat( ) ,read( ) , write ( ) ,dup( ) , close ( ) 
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Os9fork - create a process 
USAGE 

os9fork(modname,paramsize, par amp tr , type , lang,datasize) 
char *modname, *paramptr ; 

ASSEMBLER EQUIVALENT 

os9 F$FORK 

DESCRIPTION 

The action of F$FORK is described fully in the OS-9 System 
Programmer's Manual. 0s9fork will create a process that will 
run concurrently with the calling process. When the forked 
process terminates, it will return to the calling process. 

"Modname" should point to the name of the desired module. 
"Paramsize" is the length of the parameter string which should 
normally be terminated with a '\n', and "paramptr" points to 
the parameter string. "Type" is the module type as found in 
the header(normally 1: program), and "lang" should match the 
language nibble in the module header( C programs have 1 for 
6809 machine code here). "Datasize" may be zero, or it may 
contain the number of 256 byte pages to give to the new process 
as initial allocation of memory. 

DIAGNOSTICS 

-1 will be returned on error, or the ID number of the child 
process will be returned on success. 
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Pause - halt and wait for interrupt 
USAGE 

pause( ) 
ASSEMBLER EQUIVALENT 

os9 I$SLEEP with a value of 

DESCRIPTION 

Pause may be used to halt a task until an interrupt is received 
from "kill". 

Pause always returns -1 . 

SEE ALSO 

kill( ) ,signal( ) OS-9 shell command "kill" 
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Prerr - print error message 
OSAGE 

prerr(filnum,errcode) 
ASSEMBLER EQUIVALENT 

os9 F$PERR 
DESCRIPTION 



PREBR prints an error message on the output path as specified 
by "filnum" which must be the path number of an open file. The 
message depends on "errcode" which will normally be a standard 
OS-9 error code. 
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Read, Readln - read from a file 
USAGE 

read(pn, buffer, count) 
char "buffer; 

readln( pn, buffer , count) 
char "buffer; 

ASSEMBLER EQUIVALENT 

os9 I$READ 

os9 I$READLN 

DESCRIPTION 

The path number, "pn", is an integer which is one of the 
standard path numbers 0, 1 , or 2 , or the path number should 
have been returned by a successful call to "open", "creat", or 
"dup". "Buffer" is a pointer to space with at least "count" 
bytes of memory into which read will put the data from the 
file. 

It is guaranteed that at most "count" bytes will be read, but 
often less will be, either because, for readln, the file 
represents a terminal and input stops at the end of a line, or 
for both, end-of-file has been reached. 

Readln causes "line-editing" such as echoing to take place and 
returns once the first "\n" is encountered in the input or the 
number of bytes requested has been read. Readln is the 
preferred call for reading from the user's terminal. 

Read does not cause any such editing. See the 0S-9 manual for 
a fuller description of the actions of these calls. 

DIAGNOSTICS 

Read and readln return the number of bytes actually read (0 at 
end-of-file) or -1 for physical i/o errors, a bad path number, 
or a ridiculous "count". 

NOTE that end-of-file is not considered an error, and no error 
indication is returned. Zero is returned on EOF. 

SEE ALSO 

open( ) , creat( ) ,dup( ) 
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Sbrk, Ibrk - request additional working memory 
USAGE 



char *sbrk( increase) 
char «ibrk( increase) 



DESCRIPTION 

Sbrk requests an allocation from free memory and returns a 
pointer to its base. 

n Sbrk() n requests the system to allocate "new" memory from 
outside the initial allocation. 

Users should read the Memory Management section of this manual 
for a fuller explanation of the arrangement. 

Ibrk requests memory from inside the initial memory allocation. 

DIAGNOSTICS 

Sbrk and ibrk return -1 if the requested amount of contiguous 
memory is unavailable. 
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Setpr - set process priority 
USAGE 

setpr (pid, priority) 
ASSEMBLER EQUIVALENT 

os9 F$SPRIOR 
DESCRIPTION 



SETPR sets the process identified by "pid" ( process id) to have 
a priority of "priority". The lowest priority is and the 
highest is 255. 



DIAGNOSTICS 



The call will return -1 if the process does not have the same 
user id as the caller. 
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Setime.Getime - Set and get system time 

USAGE 

^include <time.h> 

setime (byff er ) 

getime(buf f er ) 

struct sgtbuf "buffer /* defined in time.h */ 

ASSEMBLER EQUIVALENT 

os9 F$STIME 
os9 G$GTIME 

DESCRIPTION 

GETIME returns system time in buffer. 
SETIME sets system time from buffer. 
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Setuid - set user id 
USAGE 

setuid(uid) 
ASSEMBLER EQUIVALENT 

os9 F$SUSER 
DESCRIPTION 



This call may be used to set the user id for the current task. 
Setuid only works if the caller is the super user(user id 0). 



DIAGNOSTICS 



Zero is returned from a successful call, and -1 is returned on 
error. 



SEE ALSO 

getuid() 
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Setstat - set file status 

USAGE 

#include <sgstat.h> 

setstat(code, filenum, buffer) /* code */ 

char "buffer; 

setstat ( code , filenum, size) /» code 2 */ 
long size; 

ASSEMBLER EQUIVALENT 

os9 F$SETSTT 

DESCRIPTION 

For a detailed explanation of this call, see the OS-9 System 
Programmer's Manual. 

"Filenum" must be the path number of a currently open file. 
The only values for code at this time are and 2. When "code" 
is 0, "buffer" should be the address of a 32 byte structure 
which is written to the option section of the path descriptor 
of the file. The header file contains definitions of various 
structures maintained by OS-9 for use by the programmer. When 
code is 2 , "size" should be a long integer specifying the new 
file size. 
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Signal - catch or ignore interrupts 



USAGE 



#include <signal.h> 

(•signal (interrupt, address) ) ( ) 
(•address) ( ) ; 

(Which means: "signal" returns a pointer to a function, 
"address" is a pointer to a function.) 



DESCRIPTION 



This call is a comprehensive method of catching or ignoring 
signals sent to the current process. Notice that "kill() n does 
the sending of signals, and "signalO" does the catching. 

Normally, a signal sent to a process causes it to terminate 
with the status of the signal. If, in advance of the 
anticipated signal, this system call is used, the program has 
the choice of ignoring the signal or designating a function to 
be executed when it is received. Different functions may be 
designated for different signals. 

The values for "address" have the following meanings: 







reset to the default i.e. 



abort when received 



1 = ignore; this will apply until reset to another 

value 

Otherwise: taken to be the address of a C function which 

is to be executed on receipt of the signal. 

If the latter case is chosen, when the signal is received by 
the process the "address" is reset to 0, the default, before 
the function is executed. This means that if the next signal 
received should be caught then another call to "signal()" 
should be made immediately. This is normally the first action 
taken by the "interrupt" function. The function may access the 
signal number which caused its execution by looking at its 
argument. On completion of this function the program resumes 
at the point at which it was "interrupted" by the signal. 

An example should help to clarify all this. Suppose a program 
needs to create a temporary file which should be deleted before 
exiting. The body of the program might contain fragments like 
this: 



pn = creat("temp" ,3) ; 
signal ( 2, i n tr upt ) ; 
signal ( 3 , intrupt ) ; 
write (pn, string, count) ; 



/• create a temporary file •/ 
/• ensure tidying up •/ 



/• 



write to temporary file •/ 
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close(pn) ; 
unlink( "temp" ) ; 
exit(O) ; 



/• finished writing •/ 
/« delete it */ 
/* normal exit */ 



The call to "signal ()" will ensure that if a keyboard or quit 
signal is received then the function n intrupt()" will be 
executed and this might be written: 



intrupt(sig) 

{ 

close (pn) ; 

unlink("temp" ) ; 

exit ( sig) ; 

} 



/* close it if open */ 
/* delete it •/ 
/* received signal as exit 
status*/ 



In this case, as the function will be exiting before another 
signal is received, it is unnecessary to call "signal()" again 
to reset its pointer. Note that either the function 
"intruptO" should appear in the source code before the call to 
"signal() n , or it should be pre-declared. 



The signals 
follows: 



used by OS-9 are defined in the header file as 



/* OS-9 signals «/ 
//define SIGKILL 

#define SIGWAKE 1 
#define SIGQUIT 2 
#define SIGINT 3 



/* system abort (cannot be caught or 
ignored)*/ 
/* wake up */ 
/* keyboard abort */ 
/* keyboard interrupt */ 



/* special addresses */ 

#define SIG_DFL /* reset to default «/ 

//define SIG_IGN 1 /» ignore */ 

Please note that there is another method of trapping signals, 
namely "intercept () " (q.v.). However, since "signal() n and 
"intercept( ) " are mutually incompatible, calls to both of them 
must not appear in the same program. The link-loader will 
prevent the creation of an executable program in which both are 
called by aborting with an "entry name clash" error for 
"_sigint" . 

SEE ALSO 

intercept() OS-9 shell command "kill" kill() 
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Stacksize, Freemem - obtain stack reservation size 
USAGE 



stacksize( ) 
f reemem( ) 

DESCRIPTION 

For a description of the meaning and use of this call, the user 
is referred to the Memory Management section of this manual. 

If the stack check code is in effect, a call to stacksize will 

return the maximum number of bytes of stack used at the time of 

the call. This call can be used to determine the stack size 
required by a program. 

Freemem() will return the number of bytes of the stack that has 
not been used. 
SEE ALSO 

ibrk( ) ,sbrk( ) ,freemem( ) Global variable "memend" and value 
"end" . 
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Strass - byte by byte copy 
USAGE 



_strass(s1 ,s2, count) 
char *s1 , *s2; 



DESCRIPTION 



Until such time as the compiler can deal with structure 
assignment, this function is useful for copying one structure 
to another. 

"Count" bytes are copied from memory location at n s2" to memory 
at "s1" regardless of the contents. 
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Tsleep - put process to sleep 
USAGE 

tsleep( ticks) 
ASSEMBLER EQUIVALENT 

os9 F$SLEEP 

DESCRIPTION 

Tsleep deactivates the calling process for a specified number 
of system "ticks" or indefinitely if "ticks" is zero. A tick 
is system dependent but is usually 100ms. 

For a fuller description of this call, see the OS-9 System 
Programmer's Manual. 
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Unlink - remove directory entry 
USAGE 

unlink( fname) 
ASSEMBLER EQUIVALENT 

os9 I$DELETE 

DESCRIPTION 

Unlink deletes the directory entry whose name is pointed to by 
"fname". If the entry was the last link to the file, the file 
itself is deleted and the disc space occupied made available 
for re-use. If, however, the file is open, in any active task, 
the deletion of the actual file is delayed until the file is 
closed . 

ERRORS 

Zero is returned from a successful call, -1 if the file does 
not exist, if its directory is write-protected , or cannot be 
searched, if the file is a non-empty directory or a device. 
SEE ALSO 

OS-9 command "kill" link() 
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Wait - wait for task termination 
USAGE 

wait(status) int "status; 

wait(O) 
ASSEMBLER EQUIVALENT 

os9 F$WAIT 

DESCRIPTION 

Wait is used to halt the current task until a child task has 
terminated . 

The call returns the task id of the terminating task and places 
the status of that task in the integer pointed to by "status" 
unless "status" is 0. A wait must be executed for each child 
task spawned. 

The status will contain the argument of the "exit" or "_exit" 
call in the child task or the signal number if it was 
interrupted. A normally terminating C program with no call to 
"exit" or "_exit" has an implied call of "exit(0)". 

CAVEATS 

NOTE that the status is the 0S-9 status code and is not 
compatible with codes on other systems. 

DIAGNOSTICS 

-1 is returned if there is no child to be waited for. 



SEE ALSO 

fork( ) , signal () ,exit( ) ,_exit() 
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Write, Writeln - write to a file or device 
USAGE 

write(pn, buffer , count) ehar "buffer; 

writeln(pn,buffer, count) char "buffer; 
ASSEMBLER EQUIVALENT 

os9 I$WRITE 

os9 I$WRITLN 
DESCRIPTION 

"Pn" must be a value returned by "open", "ereat" or "dup" or 
should be a O(stdin), l(stdout), or 2(stderr). 

"Buffer" should point to an area of memory from which "count" 

bytes are to be written. Write returns the actual number of 

bytes written, and if this is different from "count", an 
error has occurred. 

Writes in multiples of 256 bytes to file offset boundaries of 
256 bytes are the most efficient. 

Write causes no "line-editing" to occur on output. Writeln 
causes line-editing and only writes up to the first "\n" in the 
buffer if this is found before "count" is exhausted. For a 
full description of the actions of these calls the, reader is 
referred to the OS-9 documentation. 

DIAGNOSTICS 

-1 is returned if "pn" is a bad path number, if "count" is 
ridiculous or on physical i/o error. 

SEE ALSO 

creat( ) ,open( ) 
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INTRODUCTION TO THE C STANDARD LIBRARY 

The Standard Library contains functions which fall into two 
classes: high level I/O and convenience. 

The high level I/O functions provide facilities that are 
normally considered part of the definition of other languages; for 
example, the FORMAT "statement" of Fortran. In addition, automatic 
buffering of I/O channels improves the speed of file access because 
fewer system calls are necessary. 

The high level I/O functions should not be confused with the 
low level system calls with similar names. Nor should "file 
pointers" be confused with "path numbers". The standard library 
functions maintain a structure for each file open that holds status 
information and a pointer into the files buffer. A user program 
uses a pointer to this structure as the "identity" of the file 
(which is provided by "fopen()"), and passes it to the various 
I/O functions. The I/O functions will make the low level system 
calls when necessary. 

USING A FILE POINTER IN A SYSTEM CALL, OR A PATH NUMBER IN A 
STANDARD LIBRARY CALL, is a common mistake among beginners to C and, 
if made, will be sure to CRASH YOUR PROGRAM. 

The convenience functions include facilities for copying, 
comparing, and concatenating strings, converting numbers to strings, 
and doing the extra work in accessing system information such as the 
time. 

In the pages which follow, the functions available are 

described in terms of what they do and the parameters they expect. 

The "USAGE" section shows the name of the function and the type 

returned (if not int). The declaration of arguments are shown as 

they would be written in the function definition to indicate the 

types expected by the function. If it is necessary to include a 

file before the function can be used, it is shown in the "USAGE" 
section by "#include <filename>". 

Most of the header files that are required to be included, must 
reside in the "DEFS" directory on the default system drive. If the 
file is included in the source program using angle bracket 
delimiters instead of the usual double quotes, the compiler will 
append this path name to the file name. For example, "#include 
<stdio.h>" is equivalent to "#include /dO/def s/stdio.h" , if "/dO" is 
the path name of the default system drive. 

PLEASE NOTE that if the type of the value returned by a 
function is not INT, you should make a predeclaration in your 
program before calling it. For example, if you wish to use 
"atof() n , you should predeclare by having "double atof(); n somewhere 
in your program before a call to it. Some functions which have 
associated header files in the DEFS directory that should be 
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included, will be pre-declared for you in the header. An example of 
this is n ftell() n which is predeclared in "stdio.h". If you are in 
any doubt, read the header file. 
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Atof ,Atoi,Atol - ASCII to number conversions 

USAGE 

double atof(ptr) 
char *ptr; 

long atol(ptr) 
char *ptr; 

int atoi(ptr) 
char *ptr; 

DESCRIPTION 

Conversions of the string pointed to by "ptr" to the relevant 
number type are carried out by these functions. They cease to 
convert a number when the first unrecognized character is 
encountered . 

Each skips leading spaces and tab characters. Atof() 
recognizes an optional sign followed by a digit string that 
could possibly contain a decimal point, then an optional "e" 
or "E", an optional sign and a digit string. Atol() and atoi() 
recognize an optional sign and a digit string. 



CAVEATS 



Overflow causes unpredictable results. There are no error 
indications . 
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Fflush, Fclose - flush or close a file 
USAGE 

#include <stdio.h> 

fflush(fp) 
FILE «fp; 

folose(fp) 
FILE *fp; 

DESCRIPTION 

Fflush causes a buffer associated with the file pointer "fp" 
to be cleared by writing out to the file; of course, only if 
the file was opened for write or update. It is not normally 
necessary to call fflush, but it can be useful when, for 
example, normal output is to "stdout", and it is wished to 
send something to "stderr" which is unbuffered. If fflush 
were not used and "stdout" referred to the terminal, the 
"stderr" message will appear before large chunks of the 
"stdout" message even though the latter was written first. 

Fclose calls fflush to clear out the buffer associated with 
"fp", closes the file, and frees the buffer for use by another 
fopen call. 

The exit() system call and normal termination of a program 
causes fclose to be called for each open file. 

SEE ALSO 

System call close(), fopen(), setbuf(). 

DIAGNOSTICS 

EOF is returned if "fp" does not refer to an output file or 
there is an error on writing to the file. 
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Feof ,Ferror, Clearerr, Fileno - return status information of files 

USAGE 

#inelude <stdio.h> 

feof(fp) 
FILE «fp; 

f error( f P) 
FILE *fp; 

clearerr( f p) 
FILE «fp; 

fileno(fp) 
FILE «fp; 

DESCRIPTION 

Feof returns non-zero if the file associated with "fp" has 
reached its end. Zero is returned on error. 

Ferror returns non-zero if an error condition occurs on access 
to the file "fp"; zero is returned otherwise. The error 
condition persists, preventing further access to the file by 
other Standard Library functions, until the file is closed, 
or it is cleared by clearerr. 

Clearerr resets the error condition on the file "fp". This 

does NOT "fix" the file or prevent the error from occurring 

again; it merely allows Standard Library functions at least to 
try. 

CAVEATS 

These functions are actually macros that are defined in 
"<stdio.h>" so their names cannot be redeclared. 

SEE ALSO 

System call open(), fopen(). 
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Findstr,Findnstr - string search 
USAGE 

finds tr(pos, string, pat tern) 
char "string, "pattern; 

findnstr(pos, string, pattern, size) 
char "string, "pattern; 

DESCRIPTION 

These functions search the string pointed to by "string" for 
the first instance of the pattern pointed to by "pattern" 
starting at position "pos" (where the first position is 1 not 
0). The returned value is the position of the first matched 
character of the pattern in the string or zero if a match is 
not found. 

Findstr stops searching the string when a null byte is found in 
"string" . 

Findnstr only stops searching at position "pos" + "len" so it 
may continue past null bytes. 



CAVEATS 



The current implementation does not use the most efficient 
algorithm for pattern matching so that use on very long strings 
is likely to be somewhat slower than it might be. 



SEE ALSO 

index( ) ,rindex. 
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Fopen - open a file and return a file pointer 
USAGE 

#include <stdio.h> 

FILE *fopen( filename, action) 
char 'filename, "action; 

FILE «freopen( filename, action, streak) 
char "filename , 'action; 
FILE "stream; 

FILE *fdopen(filedes, action) 
int filedes; 
char "action; 

DESCRIPTION 

Fopen returns a pointer to a file structure (file pointer) if 

the file named in the string pointed to by "filename" can be 

validly opened with the action in the string pointed to by 
"action" . 

The valid actions are: 

"r" open for reading 

"w" create for writing 

"a" append(write) at end of file, or create for 
writing 

"r+" open for update 

"w+" create for update 

"a+" create or open for update at end of file 

"d" directory read 

Any action may have an "x" after the initial letter which 
indicates to "fopen() n that it should look in the current 
execution directory if a full path name is not given, and 
the x also specifies that the file should have execute 
permission. 

E.g. f = fopen("fred","wx") ; 

Opening for write will perform a "creat()". If a file with the 
same name exists when the file is opened for write, it will be 
truncated to zero length. Append means open for write and 
position to the end of the file. Writes to the file via 
"putcO" etc. will extend the file. Only if the file does not 
already exist will it be created. 
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NOTE that the type of a file structure is pre-defined in 
"stdio.h" as FILE, so that a user program may declare or define 
a file pointer by, for example, FILE »f; 

Three file pointers are available and can be considered open 

the moment the program runs: 

stdin the standard input - equivalent to path number 
stdout the standard output - equivalent to path number 1 
stderr standard error output- equivalent to path number 2 

All files are automatically buffered except stderr, unless a 
file is made unbuffered by a call to setbuf() (q.v.). 

Freopen is usually used to attach stdin, stdout, and stderr to 
specified files. Freopen substitutes the file passed to it 
instead of the open stream. The original stream is closed. 
NOTE that the original stream will be closed even if the open 
does not succeed. 

Fdopen associates a stream with a file descriptor. The streams 
type(r,w,a) must be the same as the mode of the open file. 



CAVEATS 

The "action" passed as an argument to fopen must be a pointer 
to a string, NOT a character. For example 

fp = fopen("fred", "r") ; is correct but 

fp = fopen( "fred", 'r ' ) ; is not. 

DIAGNOSTICS 

Fopen returns NULL (0) if the call was unsuccessful. 
SEE ALSO 



System call open() Fclose() 
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Fread, Fwrite - read/write binary data 
USAGE 

^include <stdio.h> 

fread(ptr, size, number, fp) 
FILE «fp; 

fwrite(ptr, size, number, fp) 
FILE »fp; 

DESCRIPTION 

Fread reads from the file pointed to by "fp". "Number" is the 
number of items of size "size" that are to be read starting at 
"ptr". The best way to pass the argument "size" to fread is by 
using "sizeof". Fread returns the number of items actually 
read . 

Fwrite writes to the file pointed to by "fp". "Number" is the 
number of items of size "size" reading them from memory 
starting at "ptr". 

DIAGNOSTICS 

Both functions return O(NULL) at end of file or error. 
SEE ALSO 

System calls read( ) , write( ) . Fopen( ) ,getc( ) , putc( ) , printf ( ) . 
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Fseek, Rewind, Ftell - position in a file or report current position 

USAGE 

//include <stdio.h> 

fseek(fp, offset, place) 
FILE «fp; 
long offset; 

rewind( fp) 
FILE »fp; 

long ftell(fp) 
FILE *fp; 

DESCRIPTION 

Fseek repositions the next character position of a file for 
either read or write. The new position is at "offset" bytes 
from the beginning of the file if "place" is 0, the current 
position if 1, or the end if 2. Fseek sorts out the special 
problems of buffering. 

NOTE that using "lseek() n on a buffered file will produce 
unpredictable results. 

Rewind is equivalent to "f seek( f p, 01 , ) " . 

Ftell returns the current position, measured in bytes, from the 
beginning of the file pointed to by "fp". 

DIAGNOSTICS 

Fseek returns -1 if the call is invalid. 
SEE ALSO 

System call lseek( ) . 



A/OTE : 



i 



0L ^ t^- 
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Getc.Getchar - return next character to be read from a file 
USAGE 

^include <stdio.h> 

int getc(fp) 
FILE «fp; 

int getchar() 

int getw(fp) 
FILE *fp; 

DESCRIPTION 

Getc returns the next character from the file pointed to by 
"fp". 

Getchar is equivalent to "getc(stdin) " . 

Getw returns the next two bytes from the file as an integer. 

Under OS-9 there is a choice of service requests to use when 
reading from a file. "Read() n will get characters up to a 
specified number in "raw" mode i.e. no editing will take 
place on the input stream and the characters will appear to the 
program exactly as in the file. "ReadlnO", on the other 
hand, will honor the various mappings of characters 
associated with a Serial Character device such as a terminal 
and in any case will return to the caller as soon as a carriage 
return is seen on the input. 

In the vast majority of cases, it is preferable to use 
"readln() n for accessing Serial Character devices and "read() n 
for any other file input. "GetcO" uses this strategy and, as 
all file input using the Standard Library functions is routed 
through "getc() n , so do all the other input functions. The 
choice is made when the first call to "getc() n is made after 
the file has been opened. The system is consulted for the 
status of the file and a flag bit is set in the file structure 
accordingly. The choice may be forced by the programmer by 
setting the relevant bit before a call to "getc() M . The flag 
bits are defined in "<stdio.h>" as "_SCF" and "_RBF" and the 
method is as follows: assuming that the file pointer for the 
file, as returned by "fopenO" is f, 

f->_flag |= _SCF; 

will force the use of "readln() n on input and 

f->_flag |= _RBF; 
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will force the use of "read() n . This trick may be played on 
the standard streams "stdin", "stdout" and "stderr" without the 
need for calling "fopen() n but before any input is requested 
from the stream. 

DIAGNOSTICS 

E0F(-1) is returned for end of file or error. 
SEE ALSO 

Pute( ) ,fread( ) ,fopen( ) ,gets() ,ungete( ) . 
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Gets, Fgets - input a string 
USAGE 

^include <stdio.h> 

char *gets(s) 
char *s; 

char »fgets(s,n,fp) 
char *s; 
FILE «fp; 

DESCRIPTION 

Fgets reads characters from the file "fp" and places them in 
the buffer pointed to by "s" up to a carriage return('\n') but 
not more than "n" - 1 characters. A null character is appended 
to the end of the string. 

Gets is similar to fgets, but gets is applied to "stdin" and no 
maximum is stipulated and the '\n' is replaced by a null. 

Both functions return their first arguments. 
CAVEATS 

The different treatment of the "n" by these functions is 
retained here for portability reasons. 

DIAGNOSTICS 

Both functions return NULL on end-of-file or error. 
SEE ALSO 

Puts() ,getc() , scanf () ,fread() . 
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Isalpha,Isupper,Islower,Isdigit,Isalnum,Isspace,Ispunct,Isprint, 
Iscntrl, Isascii - character classification 

USAGE 

#include <ctype.h> 

isalpha(c) 

etc. 

DESCRIPTION 

These functions use table look-up to classify characters 

according to their ascii value. The header file defines them 

as macros which means that they are implemented as fast, in- 
line code rather than subroutines. 

Each results in non-zero for true or zero for false. 

The correct value is guaranteed for all integer values in 
isascii, but the result is unpredictable in the others if the 
argument is outside the range -1 to 127. 

The truth tested by each function is as follows: 

is a letter 

is a digit 

is an upper case letter 

is a lower case letter 

is a letter or a digit 

is a space, tab character, newline, carriage 
return or formfeed 

is a control character (0 to 32) or DEL (127) 
is neither control nor alpha-numeric 
is printable (32 to 126) 
is in the range -1 to 127 
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L3tol f Ltol3 - convert between long integers and 3-byte integers 

USAGE 

13tol(lp,cp,n) 
long *lp; 
char *cp; 

ltol3(cp,lp,n) 
long «lp; 
char *cp; 

DESCRIPTION 

Certain system values, such as disc addresses, are maintained 
in three-byte form rather than four-byte; these functions 
enable arithmetic to be used on them. 

L3tol converts a vector of "n" three-byte integers pointed to 
by "cp", into a vector of long integers starting at "lp n . 

Ltol3 does the opposite. 
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Long jmp, Set jmp - jump to another function 
USAGE 

include <setjmp.h> 

set jmp(env) 
jmp_buf env; 

longjmp(env, val) 
jmp_buf env; 

DESCRIPTION 

These functions allow the return of program control directly to 
a higher level function. They are most useful when dealing 
with errors and interrupts encountered in a low level routine. 

"Goto" in C has scope only in the function in which it is 
used; i.e. the label which is the object of a "goto" may only 
be in the same function. Control can only be transferred 
elsewhere by means of the function call, which, of course, 
returns to the caller. In certain abnormal situations a 
programmer would prefer to be able to start some section of 
code again, but this would mean returning up a ladder of 
function calls with error indications all the way. 

Setjmp is used to "mark" a point in the program where a 
subsequent longjmp can reach. It places in the buffer, defined 
in the header file, enough information for longjmp to restore 
the environment to that existing at the relevant call to 
setjmp. 

Longjmp is called with the environment buffer as an argument 
and also, a value which can be used by the caller of setjmp as, 
perhaps, an error status. 

To set the system up, a function will call setjmp to set up the 
buffer, and if the returned value is zero, the program will 
know that the call was the "first time through". If, however, 
the returned value is non-zero, it must be a longjmp returning 
from some deeper level of the program. 

NOTE that the function calling setjmp must NOT HAVE RETURNED 
at the time of calling longjmp, and the environment buffer must 
be declared GLOBALLY. 
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Malloc, Free, Calloc - memory allocation 

USAGE 

char *malloc( size) 
unsigned size; 

free(ptr ) 
char *ptr; 

char *calloc(nel , elsize) 
unsigned nel, elsize; 

DESCRIPTION 

Malloc returns a pointer to a block of at least "size" free 
bytes. 

Free requires a pointer to a block that has been allocated by 
malloc; it frees the space to be allocated again. 

Calloc allocates space for an array. Nel is the number of 
elements in the array, and elsize is the size of each element. 
Calloc initializes the space to zero. 

DIAGNOSTICS 

Malloc, free, and calloc return NULL(O) if no free memory can 
be found or if there was an error. 
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Mktemp - create unique temporary file name 
USAGE 



char *mktemp(name) 
char *name; 

DESCRIPTION 

Mktemp may be used to ensure that the name of a temporary file 
is unique in the system and does not clash with any other file 
name. 

"Name" must point to a string whose last five characters are 
"X"; the Xs will be replaced with the ascii representation of 
the task id. 

For example, if "name" points to "foo.XXXXX", and the task id 
is 351 , the returned value points at the same place, but it now 
holds "foo.351". 

SEE ALSO 

System call "getpidO". 
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Printf .Fprintf .Sprintf - formatted output 
USAGE 

#include <stdio.h> 

printf (control [ , argO[ , argl . . ] ] ) 
char 'control; 

fprintf (fp, control [ , argO[ , argl . . ] ] ) 
FILE «fp; 
char 'control; 

sprintf(string, control [ ,argO[ ,arg1 . . ] ]) 
string []; 
char 'control; 

DESCRIPTION 

These three functions are used to place numbers and strings on 
the output in formatted, human readable form. 

Fprintf places its output on the file "fp", printf on the 
standard output, and sprintf in the buffer pointed to by 
"string". NOTE that it is the user's responsibility to ensure 
that this buffer is large enough. 

The "control" string determines the format, type, and number 
of the following arguments expected by the function. If the 
control does not match the arguments correctly, the results 
are unpredictable. 

The control may contain characters to be copied directly to 
the output and/or format specifications. Each format 
specification causes the function to take the next successive 
argument for output. 

A format specification consists of a n %" character followed by 
(in this order) : 

An optional minus sign ("-") that means left justification 
in the field. 

An optional string of digits indicating the field width 
required. The field will be at least this wide and may be 
wider if the conversion requires it. The field will be 
padded on the left unless the above minus sign is present, 
in which case it will be padded on the right. The padding 
character is, by default, a space, but if the digit string 
starts with a zero ("0"), it will be "0". 



Page 4-19 



MICROWARE C COMPILER USER'S GUIDE 
C STANDARD LIBRARY 



An optional dot (".") and a digit string, the precision, 
which for floating point arguments indicates the number 
of digits to follow the decimal point on conversion, and 
for strings, the maximum number of characters from the 
string argument are to be printed. 

An optional character "1" indicates that the following 
n d n ,"x n , or "o" is the specification of a long integer 
argument. NOTE that in order for the printing of long 
integers to take place, the source code must have in it 
somewhere the statement pflinitn . which causes routines 
to be linked from the library . 

A conversion character which shows the type of the 
argument and the desired conversion. The recognized 
conversion characters are: 

d,o,x,X The argument is an integer and the 

conversion is to decimal, octal, or 
hexadecimal, respectively. "X n prints hex 
and alpha in upper case. 

u The argument is an integer and the 

conversion is to an unsigned decimal in 
the range to 65535. 

f The argument is a double, and the form of 

the conversion is " [-]nnn. nnn" . Where the 
digits after the decimal point are 
specified as above. If not specified, the 
precision defaults to six digits. If the 
precision is 0, no decimal point or 
following digits are printed. 

e,E The argument is a double and the form of 

the conversion is "[-]n. nnne(+or-)nn" ; one 
digit before the decimal point, and the 
precision controls the number following. 
"E" prints the "e" in upper case. 

g,G The argument is a double, and either the 

"f" format or the "e" format is chosen, 
whichever is the shortest. If the "G n 
format is used, the "e" is printed in 
upper case. 

NOTE in each of the above double conversions, the last digit is 
rounded . 

ALSO NOTE that in order for the printing of floats or doubles 
£p_ take place, the source program MUST have the statement 
pffinitO somewhere . 
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c The argument is a character. 

s The argument is a pointer to a string. 

Characters from the string are printed up 
to a null character, or until the number of 
characters indicated by the precision have 
been printed. If the precision is or 
missing, the characters are not counted. 

% No argument corresponding; n % n is printed. 

SEE ALSO 

Kernighan & Ritchie pages 145-1 47 . Putc( ) , scanf ( ) . 
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Putc,Putchar,Putw - put character or word in a file 
USAGE 

//include <stdio.h> 

char putc(ch,fp) 
char ch; 
FILE «fp; 

char putchar(ch) 
char *ch; 



putw( n, fp) 
FILE «fp; 



DESCRIPTION 



Putc adds the character "ch" to the file "fp" at the current 
writing position and advances the position pointer. 

Putchar is implemented as a macro (defined in the header file) 
and is equivalent to "putc (ch, stdout ) " . 

Putw adds the (two byte) machine word "n" to the file "fp" in 
the manner of putc. 

Output via putc is normally buffered except 

(a) when the buffering is disabled by "setbuf()", and 

(b) the standard error output is always unbuffered. 

DIAGNOSTICS 

Putc and putchar return the character argument from a 
successful call, and EOF on end-of-file or error. 

SEE ALSO 

Fopen() , f close () ,fflush() ,getc() ,puts() ,printf() ,fread(). 
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Put3,Fputs - put a string on a file 
USAGE 

//include <stdio.h> 

puts(s) 
char *s; 

fputs(s,fp) 
char *s; 
FILE *fp; 

DESCRIPTION 

Fputs copies the (null-terminated) string pointed to by "s" 
onto the file "fp". 

Puts copies the string "s" onto the standard output and 
appends "\n". 

The terminating null is not copied by either function. 

CAVEATS 

The inconsistency of the new-line being appended by puts and 
not by fputs is dictated by history and the desire for 
compatibility. 
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Qsort - quick sort 

USAGE 

qsort(base,n,size, compfunc) 

char *base; 

int (*compfunc) ( ) ; /• which means: a pointer to a function 

returning an int »/ 

DESCRIPTION 

Qsort implements the quick-sort algorithm for sorting an 
arbitrary array of items. 

"Base" is the address of the array of "n" items of size "size". 
"Compfunc" is a pointer to a comparison routine supplied by 
the user. It will be called by qsort with two pointers to 
items in the array for comparison and should return an integer 
which is less than, equal to, or greater than where, 
respectively, the first item is less than, equal to, or greater 
than the second. 
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Scanf ,Fscanf ,Sscanf - input string interpretation 
USAGE 

//include <stdio.h> 

f scanf (fp, control, [ .pointer...]) 
FILE *fp; 
char "control; 

scanf ( control [ .pointer. . . ]) 
char "control; 

sscanf ( string, control [ .pointer. . . ]) 
char "string, "control ; 

DESCRIPTION 

These functions perform the complement to "printf() n etc. 

Fscanf performs conversions from the file "fp", scanf from the 
standard input, and sscanf from the string pointed to by 
"string" . 

Each function expects a control string containing conversion 
specifications, and zero or more pointers to objects into which 
the converted values are stored. 

The control string may contain three types of fields: 

(a) Spaces, tab characters, or "\n" which match any of 
the three in the input. 

(b) Characters not among the above and not "% n which must 
match characters in the input. 

(c) A "%" followed by an optional "*" indicates 
suppression of assignment, an optional field width 
maximum and a conversion character indicating the 
type expected. 

A conversion character controls the conversion to be applied 
to the next field and indicates the type of the corresponding 
pointer argument. A field consists of consecutive non-space 
characters and ends at either a character inappropriate for the 
conversion or when a specified field width is exhausted. 
When one field is finished, white-space characters are passed 
over until the next field is found. 

The following conversion characters are recognized : 

d A decimal string is to be converted to an integer, 
o An octal string; the corresponding argument should 

point to an integer. 
x A hexadecimal string for conversion to an integer, 
s A string of non-space characters is expected and 
will be copied to the buffer pointed to by the 
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corresponding argument and a null ("\0") appended. 
The user must ensure that the buffer is large 
enough. The input string is considered terminated 
by a space, tab or ("\n"). 

c A character is expected and is copied into the byte 
pointed to by the argument. The white-space 
skipping is suppressed for this conversion. If a 
field width is given, the argument is assumed to 
point to a character array and the number of 
characters indicated is copied to it. NOTE to ensure 
that the next non-white-space character is read use 
"%1s" and that TWO bytes are pointed to by the 
argument . 

e,f A floating point representation is expected on the 
input and the argument must be a pointer to a float. 
Any of the usual ways of writing floating point 
numbers are recognized. 

[ This denotes the start of a set of match characters; 
the inclusion or exclusion of which delimits the 
input field. The white-space skipping is 
suppressed. The corresponding argument should be a 
pointer to a character array. If the first 
character in the match string is not ""n, 
characters are copied from the input as long as they 
can be found in the match string, if the first 
character is the copying continues while characters 
cannot be found in the match string. The match 
string is delimited by a "]". 
D,0,X Similar to d,o,x above, but the corresponding 
argument is considered to point to a long integer. 

E,F Similar to e,f above, but the corresponding argument 
should point to a double. 

% A match for "%" is sought; no conversion takes 

place. 

Each of these functions returns a count of the number of 
fields successfully matched and assigned. 

CAVEATS 

The returned count of matches/assignments does not include 
character matches and assignments suppressed by "*". The 
arguments must ALL be pointers. It is a common error to call 
scanf with the value of an item rather than a pointer to it. 

DIAGNOSTICS 

These functions return EOF on end of input or error and a count 
which is shorter than expected for unexpected or unmatched 
items. 

SEE ALSO 

Atoi( ) ,Atof() ,Getc( ) ,Printf () Kernighan and Ritchie pp 147-150 
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Setbuf - fix file buffer 
USAGE 

#include <stdio.h> 



setbuf(fp, buffer) 
FILE »fp; 
char "buffer; 

DESCRIPTION 

When the first character is written to or read from a file 
after it has been opened by "fopen() n , a buffer is obtained 
from the system if required and assigned to it. Setbuf may be 
used to forestall this by assigning a user buffer to the file. 

Setbuf must be used after the file has been opened and before 
any I/O has taken place. 

The buffer must be of sufficient size and a value for a 
manifest constant, BUFSIZ, is defined in the header file for 
use in declarations. 

If the "buffer" argument is NULL (0), the file becomes un- 
buffered and characters are read or written singly. 

NOTE that the standard error output is unbuffered and the 
standard output is buffered. 

SEE ALSO 

fopen() ,getc( ) ,putc() . 
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Sleep - stop execution for a time 
USAGE 



sleep(seoonds) 
unsigned seconds; 



DESCRIPTION 



The current task is stopped for the specified time. 

If "seconds" is zero, the task will sleep for one tick. 
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Stroat, Strncat, Strcmp, Strncmp, Strcpy, Strhcpy, Strnopy, 
Strlen, Index, Rindex- string functions 



USAGE 



char *strcat(s1 ,s2) 
char «s1 ,*s2; 

char »strncat(s1 ,s2 ,n) 
char *s1 , *s2; 
int n; 

strcmp(s1 ,s2) 
char *s1 , *s2; 

char *strhcpy(s1 ,s2) 
char *s1 , «s2; 

strncmp(s1 ,s2 ,n) 
char *s1 , »s2; 
int n; 

char *strcpy( s1 , s2) 
char *s1 , *s2; 

char »strncpy(s1 ,s2 ,n) 
char *s1 , *s2; 
int n; 

strlen(s) 
char *s; 

char *index(s,ch) 
char *s,ch; 

char *rindex(s, ch) 
char *s,eh; 



DESCRIPTION 



All strings passed to these functions are assumed null- 
terminated . 

Strcat appends a copy of the string pointed to by n s2 n to the 
end of the string pointed to by "s1". Strncat copies at most 
"n" characters. Both return the first argument. 

Strcmp compares strings n s1 n and n s2 n for lexicographic order 
and returns an integer less than, equal to or greater than 
where, respectively, "si" is less than, equal to or greater 
than n s2". Strncmp compares at most n n" characters. 
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Strepy copies characters from "s2" to the space pointed to by 
"si" up to and including the null byte. Strncpy copies exactly 
"n" characters. If the string "s2" is too short, the n s1" will 
be padded with null bytes to make up the difference. If n s2 n 
is too long, n s1 n may not be null-terminated. Both functions 
return the first argument. 

Strncpy copies string with sign bit terminator. 

Strlen returns the number of non-null characters in "s". 

Index returns a pointer to the first occurrence of "oh" in "s" 
or NULL if not found. 

Rindex returns a pointer to the last occurrence of "oh" in "s" 
or NULL if not found. 

CAVEATS 

Strcat and strepy have no means of checking that the space 
provided is large enough. It is the user's responsibility to 
ensure that string space does not overflow. 

SEE ALSO 

Findstr( ) . 
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System - shell command request 
USAGE 



system( string) 
char 'string; 

DESCRIPTION 

System passes its argument to "shell" which executes it as a 
command line. The task is suspended until the shell command 
is completed and system returns the shell's exit status. The 
maximun length of string is 80 characters. If a longer string 
is needed, use os9fork. 

SEE ALSO 

System calls "os9fork( ) " , "wait( ) " . 
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Toupper,Tolower - character translation 
USAGE 

#include <ctype.h> 

int toupper(c) 
int c; 

etc . 

int _toupper(c) 
int c ; 

int _tolower(c) 
int c ; 

DESCRIPTION 

The functions toupper and tolower have as their domain the 
integers in the range -1 through 255. Toupper converts lower- 
case to upper-case, and tolower converts upper-case to lower- 
case. All other arguments are returned unchanged. 

The macros _toupper and _tolower do the same things as the 
corresponding functions, but they have restricted domains and 
they are faster. The argument to _toupper must be lower-case, 
and the argument to _tolower must be upper-case. Arguments 
that are outside each macros domain, such as passing a lower- 
case to _tolower, yield garbage results. 
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Ungetc - put character back on input 
USAGE 

^include <stdio.h> 



ungeto( ch, f p) 
char ch; 
FILE »fp; 



DESCRIPTION 

This function alters the state of the input file buffer such 
that the next call of "getc() n returns "ch". 

Only one character may be pushed back, and at least one 
character must have been read from the file before a call to 
ungetc. 

M Fseek()" erases any pushback. 

DIAGNOSTICS 

Ungetc returns its character argument unless no pushback could 
occur, in which case EOF is returned. 

SEE ALSO 

getc( ) ,fseek( ) 



Z-MT V A A <A <0U 

Vb/6ZTC pAS 



Page 4-33 



MICROWARE C COMPILER USER'S GUIDE 
C STANDARD LIBRARY 



Page 4-34 



MICEOWARE C COMPILER USER'S GUIDE 
APPENDIX A 



COMPILER GENERATED ERROR MESSAGES 



Below is a list of the error messages that the C compiler generates, 
and, if applicable, probable causes and the K & R Appendix A section 
number (in parenthesis) to see for more specific information. 



already a local variable 

Variable has already been declared at the current block level. 
(8.1, 9.2) 

argument : <text> 

Error from preprocessor. Self-explanatory. Most common cause 
of this error is not being able to find an include file. 

argument error 

Function argument declared as type struct, union, or function. 
Pointers to such types, however, are allowed. (10.1) 

argument storage 

Function arguments may only be declared as storage class 
register. (10.1) 

bad character 

A character not in the C character set (probably a control 
char) was encountered in the source file. (2) 

both must be integral 

>> and << operands cannot be FLOAT or DOUBLE. (7.5) 

break error 

The break statement is allowed only inside a while, do, for, or 
switch block. (9.8) 

can't take address 

& operator is not allowed on a register variable. Operand must 
otherwise be an lvalue. (7.2) 

cannot cast 

Type result of cast cannot be FUNCTION or ARRAY. (7.2, 8.7) 

cannot evaluate size 

Could not determine size from declaration or initializer. 
(8.6, 14.3) 

cannot initialize 

Storage class or type does not allow variable to be 
initialized. (8.6) 

compiler trouble 

Compiler detected something it couldn't handle. Try compiling 
the program again. If this error still occurs, contact Radio 
Shack. 
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condition needed 

While, do, for, switch, and if statements require a condition 
expression. (9.3) 

constant expression required 

Initializer expressions for static or external variables cannot 
reference variables. They may, however, refer to the address 
of a previously declared variable. This installation allows no 
initializer expressions unless all operands are of type INT or 
CHAR (8.6) 

constant overflow 

Input numeric constant was too large for the implied or 
explicit type. (2.6, [PDP-11]) 

constant required 

Variables are not allowed for array dimensions or cases. (8.3, 
8.7, 9.7) 

continue error 

The continue statement is allowed only inside a while, do, or 
for block. (9.9) 

declaration mismatch 

This declaration conflicts with a previous one. This is 
typically caused by declaring a function to return a non- 
integer type after a reference has been made to the function. 
Depending on the line structure of the declaration block, this 
e 
declaration. (11, 11.1 11.2) 



rror may be reported on the line following the erroneous 



divide by zero 

Divide by zero occurred when evaluating a constant expression. 

? expected 

? is any character that was expected to appear here. Missing 
semicolons or braces cause this error. 

expression missing 

An expression is required here. 

function header missing 

Statement or expression encountered outside a function. 
Typically caused by mismatched braces. (10.1) 

function type error 

A function cannot be declared as returning an array, function, 
struct, or union. (8.4, 10.1) 

function unfinished 

End-of-file encountered before the end of function definition. 
(10.1) 

identifier missing 

Identifier name required here but none was found. 
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illegal declaration 

Declarations are allowed only at the beginning of a block. 
(9.2) 

label required 

Label name required on goto statement. (9.11) 

label undefined 

Goto to label not defined in the current function. (9.12) 

lvalue required 

Left side of assignment must be able to be "stored into". 
Array names, functions, structs, etc. are not lvalues. (7.1) 

multiple defaults 

Only one default statement is allowed in a switch block. (9-7) 

multiple definition 

Identifier name was declared more than once in the same block 
level (9.2, 11.1) 

must be integral 

Type of object required here must be type int, char, or 
pointer. 

name clash 

Struct-union member and tag names must be mutually distinct. 
(8.5) 

name in a cast 

Identifier name found in a cast. Only types are allowed. (7.2, 
8.7) 

named twice 

Names in a function parameter list may appear only once. (10.1) 

no 'if for 'else' 

Else statement found with no matching if. This is typically 
caused by extra or missing braces and/or semicolons. (9.3) 

no switch statement 

Case statements can only appear within a switch block. (9-7) 

not a function 

Primary in expression is not type "function returning...". If 
this is really a function call, the function name was declared 
differently elsewhere. (7.1) 

not an argument 

Name does not appear in the function parameter list. (10.1) 

operand expected 

Unary operators require one operand, binary operators two. 
This is typically caused by misplaced parenthesis, casts or 
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(7.1) 



memory overflow. The compiler requires 
for symbol table entries, block level 
code generation. Three major factors affect 

„ „-. Permanent declarations (those appearing on 

the outer block level (used in include files)) must be reserved 
from the dynamic memory for the duration of the compilation of 
the file. Each { causes the compiler to perform a block-level 
recursion which may involve "pushing down" previous 
declarations which consume memory. Auto class initializers 
require saving expression trees until past the declarations 
which may be very memory-expensive if they exist. Avoiding 
excessive declarations, both permanent and inside compound 
statement blocks, conserve memory. If this error occurs on an 
auto initializer, try initializing the value in the code body. 



pointer mismatch 

Pointers refer to different types. 
(7.1) 



Use a cast if required. 



pointer or integer required 

A pointer (of any type) or integer is required to the left of 
the '->' operator. (7.1) 

pointer required 

Pointer operand required with unary * operator. (7.1) 

primary expected 

Primary expression required here. (7.1) 

should be NULL 

Second and third expression of ?: conditional operator cannot 
be pointers to different types. If both are pointers, they 
must be of the same type or one of the two must be null. (7.13) 

•<«• STACK OVERFLOW «*«* 

Compiler stack has overflowed. Most likely cause is very deep 
lock-level nesting or hundreds of switch cases. 

storage error 

Reg and auto storage classes may only be used within functions. 
(8.1) 

struct member mismatch 

Identical member names in two different structures must have 
the same type and offset in both. (8.5) 



struct member required 

Identifier used with 
member name. (7.1) 



and -> operators must be a structure 



struct syntax 

Brace, comma, etc. is missing in a struct declaration. (8.5) 
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struct or union inappropriate 

Struct or union cannot be used in this context. 

syntax error 

Expression, declaration, or statement is incorrectly formed. 

third expression missing 

? must be followed by a : with expression. This error may be 
caused by unmatched parenthesis or other errors in the 
expression. (7.13) 

too long 

Too many characters provided in a string initializing a 
character array. (8.6) 

too many brackets 

Unmatched or unexpected brackets encountered processing an 
initializer. (8.6) 

too many elements 

More data items supplied for aggregate level in initializer 
than members of the aggregate. (8.6) 

type error 

Compiler type matching error. Should never happen. 

type mismatch 

Types and/or operators in expression do not correspond. (6) 

typedef - not a variable 

Typedef type name cannot be used in this manner. (8.8) 

undeclared variable 

No declaration exists at any block level for this identifier. 

undefined structure 

Union or struct declaration refers to an undefined structure 
name. (8.5) 

unions not allowed 

Cannot initialize union members. (8.6) 

unterminated character constant 

Unmatched ' character delimiters. (2.4.3) 

unterminated string 

Unmatched " string delimiters. (2.5) 

while expected 

No while found for do statement. (9.5) 
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COMPILER PHASE COMMAND LINES 



This appendix describes the command lines and options for the 

individual compiler phases. Each phase of the compiler may be 

executed separately. The following information describes the 
options available to each phase. 

cc1 & cc2 (C executives): 

cc [options] file {file} [options] 

Recognized file suffixes: 

.c C source file 

.a Assembly language source file 

.r Relocatable module format file 

Recognized options: (UPPER and lower case is equiv.) 

-a Suppress assembly. Leave output in ".a" file. 
-e=n Edition number (n) is supplied to c.prep for 

inclusion in module psect and/or to clink for 

inclusion as the edition number of the linked 

module, 
-o Inhibits assembler code optimizer pass, 
-p Invoke compiler function profiler, 
-r Suppress link step. Leave output in ",r" file. 
-m=<size> Size in pages (in kbytes if followed by a K) of 

additional memory the linker should allocate to 

object module. 
-l=<path> Library file for linker to search before the 

standard library. 
-f=<path> Overrride other output naming. Module name (in 
object module) is the last name in the pathlist. 
-f is not allowed with -a or -r. 
-o Output comments in assembly language code, 
-s Suppress generation of stack-checking code. 
-d<NAME> Is equiv to #define <NAME> 1 in the 

preprocessor. -d<NAME>=<STRING> is equivalent to 

//define <NAME> <STRING>. 

-n=<name> output module name. <name> is used to override 
the -f default output name. 

CC1 only: 

-x Create, but do not execute c.com command file. 

CC2 only: 

-q Quiet mode. Suppress echo of file names. 
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c.prep (C macro preprocessor) 
c.prep [options] <path> 

<path> is read as input. C.prep causes c.comp to generate a 
psect directive with the last element of the pathlist and _c as 
the psect name. If <path> is /dO/myprog. c, the psect name is 
myprog_c. Output is always to stdout. 

Recognized options: 

-1 Cause c.comp to copy source lines to assembly 

output as comments. 
-E=<n> 

-e=<n> Use <n> as psect edition number. 
-D<NAME> Same as described above for cc1/ec2. 



c.comp (One-pass compiler) 

c.comp [options] [<file>] [options] 

If <file> is not present, c.comp will read stdin. Input text 
need not be c.prep output, but no preprocessor directives are 
recognized (//include, #define, macros etc.). Output assembly 
code is normally to stdout. Error message output is always 
written to stdout. 

Recognized options: 

-s Suppress generation of stack checking code, 
-p Generate profile code. 
-o=<path> Write assembly output to <path>. 



c.passl (Pass One of Two-pass Compiler) 
c.pass2 (Pass Two of Two-pass Compiler) 

c.passl [options] [<file>] [options] 
c.pass2 [options] [<file>] [options] 

Command line and options are the same as c.comp. If the 
options given to c.passl are not given to c.pass2 also, c.pass2 
will not be able to read the c.passl output. Both c.passl and 
c.pass2 read stdin and write stdout normally. 
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c.opt (Assembly code optimizer) 

e.opt [<inpath>] [<outpath>] 

C.opt reads stdin and writes stdout. <inpath> must be present 
if <outpath> is given. Since c.opt rearranges and changes 
code, comments and assembler directives may be rearranged. 

c.asm (Assembler) 

c.asm <file> [options] 

C.asm reads <file> as assemble language input. Errors are 
written to stderr. Options are turned on or off by the 
inclusion of the option character preceeded by a '-'. 

Recognized options: 

-o=<path> Write relocatable output to path. Must be a 

disk file. 
-1 Write listing to stdout. (default off) 
-c List conditional assembly lines, (default on) 
-f Formfeed for top of form, (default off) 
-g List all code bytes generated, (default off) 
-x Suppress macro expansion listing, (default on) 
-e Print errors, (default on) 
-s Print symbol table, (default off), 
-dn Set lines per page to n. (default 66). 
-wn Set line width to n. (default 80). 

clink (Linker) 

clink [options] <mainline> [<sub1> {<subn>} ] [options] 

Clink turns c.asm output into executable form. All input 
files must contain relocatable object format (ROF) files. 
<mainline> specifies the base module from which to resolve 
external references. A mainline module is indicated by setting 
the type/lang value in the psect directive non-zero. No other 
ROF can contain a mainline psect. The mainline and all 
subroutine files will appear in the final linked object module 
whether actually referenced or not. 

For the C Compiler, cstart.r is the mainline module. It is the 
mainline module's job to perform the initialization of data and 
the relocation of any data-text and data-data references within 
the initialized data using the information in the object module 
supplied by clink. 
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(clink continued) 

Recognized options: 

-o=<path> Linker object output file must be a disk 

file. The last element in <path> is used as the 
module name unless overridden by -n. 

-n=<name> Use <name> as output module name. 

-l=<path> Use <path> as library file. A library file 

consists of one or more merged assembly ROF 
files. Each psect in the file is checked to see 
if it resolves any unresolved references. If 
so, the module is included in the final output 
module, otherwise it is skipped. No mainline 
psects are allowed in a library file. Library 
files are searched in the order given on the 
command line. 

-E=<n> 

-e=<n> <n> is used for the edition number in the final 
output module. 1 is used if -e is not present. 

-M=<size> <size> indicates the number of pages (kbytes if 
size is followed by a K) of additional memory, 
clink will allocate to the data area of the 
final object module. If no additional memory is 
given, clink adds up the total data stack 
requirements found in the psect of the modules 
in the input modules. 

-m Prints linkage map indicating base addresses of 
the psects in the final object module. 

-s Prints final addresses assigned to symbols in 
the final object module. 

-b=<ept> Link C functions to be callable by BASIC09. 

<ept> is the name of the function to be 
transferred to when BASIC09 executes the RUN 
command. 

-t Allows static data to appear in a BASIC09 call- 
able module. It is assumed the C function call- 
ed and the calling BASIC09 program have provided 
a sufficiently large static storage data area 
pointed to by the Y register. 
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USING AND LINKING TO USER DEFINED LIBRARIES 

A library consists of a group of "C" procedures or functions that 
have been separately compiled into Relocatable Object Files (ROF) 
and subsequently merged into one library file. 

If, hypothetically , you had created a set of higher level mathematic 
functions, that you wanted to convert into a *C" library. First you 
would separately compile each one using the -R option. Then you 
would merge them all into one large library file. If you need to 
scan the library file for available functions you can use the 
example program "RDUMP.C to inspect any "C" library file. 

For example: 

0S9:CC1 SIN.C COS.C TAN.C ARCOS.C -R 

0S9:CC1 ARCSIN.C ARCTAN.C EXP.C LOG.C -R 

0S9:CC1 NLOG.C SQRT.C SQR.C CUBE.C -R 

Then you would: 

0S9:MERGE SIN.R COS.R TAM.R ARCOS.R >TEMP1 
0S9:MERGE ARCSIN.R ARCTAN.R EXP.R LOG.R >TEMP2 
0S9:MERGE NLOG.R SQRT.R SQR.R CUBE.R >TEMP3 
0S9: MERGE TEMPI TEMP2 TEMP3 >TRIG.L 

Then to use the library simply use the -l=<pathlist> option in your 
command line when you compile your program. 

When the linker is executed the pathlist specified will be searched 
to resolve any references made to the functions within the library. 
The linker searches all specified libraries in the order specified 
before searching the standard library. The linker will resolve all 
references on a first found basis. This means that the linker will 
use the first procedure or function whose name matches a reference 
to that name and will ignore any additional functions found that 
have the same name. 

Procedures or functions within a library that use other functions 
within the same library should always appear first. For example, in 
the above example if the "ARCSIN" routine used the "SIN" routine, 
the "SIN" routine should be merged into the library file after the 
"ARCSIN". Another way of putting this is that all references to 
other procedures within a library should be forward references. 
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INTERFACING TO BASIC09 



The object code generated by the Microware C Compiler can be made 
callable from the BASIC09 "RUN" statement. Certain portions of a 
BASIC09 program written in C can have a dramatic effect on execution 
speed. To effectively utilize this feature, one must be familiar 
with both C and BASIC09 internal data representation and procedure 
calling protocol. 

C type "int" and BASIC09 type "INTEGER" are identical; both are two 
byte two's complement integers. C type "char" and BASIC09 type 
"BYTE" and "BOOLEAN" are also identical. Keep in mind that C will 
sign-extend characters for comparisons yielding the range -128 to 
127. 

BASIC09 strings are terminated by Oxff (255). C strings are 
terminated by 0x00 (0). If the BASIC09 string is of maximum length, 
the terminator is not present. Therefore, string length as well as 
terminator checks must be performed on BASIC09 strings when 
processing them with C functions. 

The floating point format used by C and BASIC09 are not directly 
compatible. Since both use a binary floating point format it is 
possible to convert BASIC09 reals to C doubles and vice-versa. 

Multi-dimensional arrays are stored by BASIC09 in a different manner 
than C. Multi-dimensional arrays are stored by BASIC09 in a column- 
wise manner; C stores them row-wise. Consider the following 
example: 

BASIC09 matrix: DIM array( 5 ,3 ) : INTEGER. 

The elements in consecutive memory locations (read left to 

right, line by line) are stored as: 

(1,1), (2,1), (3,1), (4,1), (5,1) 

(1,2), (2, 2), (3, 2), (4, 2), (5, 2) 

(1,3), (2, 3), (3, 3), (4, 3), (5, 3) 

C matrix: int array[ 5] t 3] ; 

The elements in consecutive memory locations (read left to 

right, line by line) are stored as: 



(1,1) 


,(1,2) 


,(1,3) 


(2,1) 


,(2,2) 


,(2,3) 


(3,1) 


,(3,2) 


,(3,3) 


(4,1) 


,(4,2) 


,(4,3) 


(5,1) 


,(5,2) 


,(5,3) 



Therefore to access 
must be transposed. 
array[2][4] in C. 



BASIC09 matrix elements in C, the subscripts 
To access element array(1,2) in BASIC09 use 



The details on interfacing BASIC09 to C are best described by 
example. The remainder of this appendix is a mini tutorial 
demonstrating the process starting with simple examples and working 
up to more complex ones. 
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EXAMPLE 1 - SIMPLE INTEGER ARITHMETIC CASE 



This first example illustrates a simple case. Write a C function to 
add an integer value to three integer variables. 

build bt1 .c 

? addints(cnt, value, s1 ,arg1 , s2 ,arg2, s3,arg3 , s4) 

? int *value, »arg1 , «arg2, *arg3; 

? { 

? *arg1 += "value; 

? *arg2 += *value; 

? *arg3 += *value; 

? } 

? 

That's the C function. The name of the function is "addints". The 
name is information for C and clink; BASIC09 will not know anything 
about the name. Page 9-13 of the BASIC09 Reference manual describes 
how BASIC09 passes parameters to machine language modules. Since 
BASIC09 and C pass parameters in a similar fashion, it is easy to 
access BASIC09 values. The first parameter on the BASIC09 stack is 
a two byte count of the number of following parameter pairs. Each 
pair consists of an address and size of value. For most C 
functions, the parameter count and pair size is not used. The 
address, however, is the useful piece of information. The address 
is declared in the C function to always be a "pointer to..." type. 
BASIC09 always passes addresses to procedures, even for constant 
values. The arguments cnt, s1, s2, s3, and s4 are just place 
holders to indicate the presence of the parameter count and argument 
sizes on the stack. These can be used to check validity of the 
passed arguments if desired. 

The line "int "value , »arg1 , »arg2 , *arg3" declares the parameters (in 
this case all "pointers to int"), so the compiler will generate the 
correct code to access the BASIC09 values. The remaining lines 
increment each arg by the passed value. Notice that a simple 
arithmetic operation is performed here (addition), so C will not 
have to call a library function to do the operation. 

To compile this function, the following C compiler command line is 
used : 

cc2 bt1 .c -rs 

Cc2 uses the Level-Two compiler. Replace cc2 with cc1 if you are 
using the Level-One compiler. The -r option causes the compiler to 
leave btl.r as output, ready to be linked. The -s option suppresses 
the call to the stack checking function. Since we will be making a 
module for BASIC09, cstart.r will not be used. Therefore, no 
initialized data, static data, or stack checking is allowed. More 
on this later. 
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The btl.r file must now be converted to a loadable module that 
BASIC09 can link to by using a special linking technique as follows: 



clink btl.r -b=addints -o = addints 



This command tells the 
"-b=addints" tells the 
BASIC09 can link to 
entrypoint in the mod 
in this mode. It re 
name given to the "-b 
to be entered directly 
"-o=addints" says what 
case "addints". This 
RUN command to call 
option is the name 
merely information to 
module entrypoint offse 



linker to read btl.r as input. The option 
linker to make the output file a module that 
and that the function "addints" is to be the 
ule. You may give many input files to clink 
solves references in the normal fashion. The 
" option indicates which of the functions is 
by the BASIC09 RUN command. The option 
the name of the output file is to be, in this 
name should be the name used in the BASIC09 
the C procedure. The name given in the n -o=" 
of the procedure to RUN. The "-b=" option is 
the linker so it can fill in the correct 
t. 



Enter the following BASIC09 program: 

PROCEDURE btest 

DIM i, j,k:INTEGER 

i=1 

j = 132 

k=-1033 

RUN addints(4,i,j,k) 

PRINT i,j,k 

END 

When this procedure is RUN, it should print: 

5 136 -1029 

indicating that our C function worked! 
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EXAMPLE 2 - MORE COMPLEX INTEGER ARITHMETIC CASE 



The next example shows how static memory area can be used. Take the 
C function from the previous example and modify it to add the number 
of times it has been entered to the increment: 

build bt2.c 

? static int entcnt; 

? 

? addints(cnt , cmem, cmemsiz , value , s1 ,arg1 , s2 ,arg2 , s3 , arg3 , s4 ) 

? char *cmem; 

? int *value, »arg1 ,*arg2, *arg3; 

? { 

? #asm 

? ldy 6,s base of static area 

? #endasm 

? int j = 'value + entcnt++; 

? 

? »arg1 += j; 

? »arg2 += j; 

? »arg3 += j; 
? 1 



This example differs from the first in a number of ways. The line 
"static int entcnt" defines an integer value named entcnt global to 
bt2.c. The parameter cmem and the line "char *cmem" indicate a 
character array. The array will be used in the C function for 
global/static storage. C accesses non-auto and non-register 
variables indexed off the Y register. Cstart.r normally takes care 
of setting this up. Since cstart.r will not be used for this 
BASIC09 callable function, we have to take measures to make sure the 
Y register points to a valid and sufficiently large area of memory. 
The line "ldy 6,s" is assembly language code embedded in C source 
that loads the Y register with the first parameter passed by 
BASIC09. If the first parameter in the BASIC09 RUN statement is an 
array, and the "ldy 6,s" is placed IMMEDIATELY after the "{" opening 
the function body, the offset will always be "6,s". Note the line 
beginning "int j = ...". This line uses an initializer which, in 
this case, is allowed because j is of class "auto". No classes but 
"auto" and "register" car. be initialized in BASIC09 callable C 
functions . 

To compile this function, the following C compiler command line is 
used : 

cc bt2.c -rs 

Where cc is cd or cc2. 

Again, the -r option leaves bt2.r as output and the -s option 
suppresses stack checking. 

Normally, the linker considers it to be an error if the "-b=" option 
appears and the final linked module requires a data memory 
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allocation. In our case here, we require a data memory allocation 
and we will provide the code to make sure everything is set up 
correctly. The n -t" linker option causes the linker to print the 
total data memory requirement so we can allow for it rather than 
complaining about it. Our linker command line is: 

clink bt2.r -o = addints -b = addints -t 

The linker will respond with "BASIC09 static data size is 2 bytes". 
We must make sure cmem points to at least 2 bytes of memory. The 
memory should be zeroed to conform to C specifications. 



Enter the following BASIC09 program: 

PROCEDURE btest 
DIM i,j,k,n:INTEGER 
DIM cmem( 10): INTEGER 
FOR i=1 TO 10 

cmem( i) =0 
NEXT i 
FOR n=1 TO 5 

i=1 

j=132 

k=-1033 

RUN addints(cmem,4 , i, j ,k) 

PRINT i,j,k 
NEXT n 
END 

This program is similar to the previous example. Our area for data 
memory is a 10 integer array (20 bytes) which is way more than the 2 
bytes for this example. It is better to err on the generous side. 
Cmem is an integer array for convenience in initializing it to zero 
(per C data memory specifications). When the program is run, it 
calls addints 5 times with the same data values. Because addints 
adds the number of times it was called to the value, the i,j,k 
values should be 4+number of times called. When run, the program 
prints : 

5 
6 
7 



136 
137 
138 
139 
140 



■1029 
■1028 
■1027 
■1026 
■1025 



Works again! 
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EXAMPLE 3 - SIMPLE STRING MANIPULATION 



This example shows how to access BASIC09 strings through C 
functions. For this example, write the C version of SUBSTR: 

build bt3.c 

? /* Find substring from BASIC09 string: 

? RUN findstr(A$,B$,fndpos) 

? returns in fndpos the position in A$ that B$ was found or 

? if not found. A$ and B$ must be strings, fndpos must be 

? INTEGER. 

? */ 

? f indstr (cnt , string, strcnt , srchstr , srchcnt , result) 

? char ^string ,*srchstr ; 

? int strcnt , srchcnt , *result; 

? { 

? *result = finder (string, strcnt , srchstr , srchcnt) ; 

? } 

? 

? static finder(str , strlen, pat ,patlen) 

? char «str,»pat; 

? int strlen, patlen; 

? { 

? int i; 

? for(i=1 ;strlen — > && *str!=0xff; ++i) 

? if (smatch( str++, pat, patlen) ) 

? return i; 

? } 

? 

? static smatch(str, pat, patlen) 

? register char *str,*pat; 

? int patlen; 

? { 

? while(patlen — > && *pat != Oxff) 

? if(«str++ != »pat++) 

? return 0; 

? return 1 ; 

? } 
? 

Compile the program: 

cc bt3.c -rs 

Where cc is cd or cc2 

And link it: 

clink bt3.r -o=findstr -b = findstr 
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The BASIC09 test program is: 

PROCEDURE btest 

DIM a,b:STRING[20] 

DIM matchpos: INTEGER 

LOOP 

INPUT "String " , a 

INPUT "Match ",b 

RUN findstr (a, b, matchpos ) 

PRINT "Matched at position ".matchpos 

ENDLOOP 

When the program is run, it should print the position where the 
matched string was found in the source string. 
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EXAMPLE 4 - QUICKSORT 



The next example programs demonstrate how one might implement a 
quicksort written in C to sort some BASIC09 data. 

C integer quicksort program: 

//define swap(a,b) { int t; t=a; a=b; b = t; ) 

/« qsort to be called by BASIC09: 

dim d( 100):INTEGER any size INTEGER array 

run cqsort(d , 1 00) calling qsort. 
»/ 

qsort (argent , iarray , iasize,icount,icsiz) 

int argent, /* BASIC09 argument count •/ 

iarray[], /* Pointer to BASIC09 integer array */ 

iasize, /* and it's size •/ 

•icount, /• Pointer to BASIC09 (sort count) */ 

icsiz; /* Size of integer »/ 

{ 

sort ( iarray ,0 , "icount ) ; /* initial qsort partition •/ 

} 

/* standard quicksort algorithm from Horowitz-Sahni */ 
static sort(a,m,n) 
register int »a,m,n; 
{ 

register i,j,x; 

if(m < n) { 

i = m; 

j = n + 1 ; 

x = a [ m ] ; 

for(;;) { 

do i += 1; while(a[i] < x) ; /* left partition »/ 
do j -= 1; while(a[j] > x); /* right partition */ 

if(i < j) 

swap(a[i] ,a[ j]) /» swap */ 

else break; 
} 

swap(a[m],a[ j]) ; 
sort(a,m, j-1 ) ; /» sort left »/ 



} 
} 



sort( a, j+1 ,n) ; /* sort right •/ 
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The BASIC09 program is: 

PROCEDURE sorter 

DIM i,n,d( 1000): INTEGER 

n=1000 

i=RND(-(PI)) 

FOR i=1 TO n 

d(i):=INT(RND(1000)) 

NEXT i 

PRINT "Before:" 

RUN prin(1 ,n,d) 

RUN qsortb(d.n) 

PRINT "After:" 

RUN prin(1 ,n,d) 

END 

PROCEDURE prin 

PARAM n,m,d( 1000) :INTEGER 

DIM i: INTEGER 

FOR i=n TO m 

PRINT d(i); " "; 

NEXT i 

PRINT 

END 

C string quicksort program: 

/* qsort to be called by BASIC09: 

dim cmemory:STRING[ 10] This should be at least as large as 

the linker says the data size should 
be. 
dim d( 100) : INTEGER Any size INTEGER array. 

run cqsort(cmemory,d, 100) calling qsort. Note that the pro- 
cedure name run is the linked 0S-9 
subroutine module. The module name 
need not be the name of the C func- 
tion. 
«/ 

int maxstr; /» string maximum length »/ 

static strbcmp(str1 ,str2) /« basic09 string compare »/ 

register char »str1,*str2; 

{ 

int maxlen; 

for (maxlen = maxstr; *str1 == *str2 ;++str1) 
if (maxlen — > ! | *str2++ == Oxff) 
return 0; 
return («str1 - *str2); 
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ossort ( argent , stor , storsiz, iarray , iasize,elemlen,elsiz , 
icount , icsiz) 

/« BASIC09 argument count »/ 
/• Pointer to string (C data storage) */ 
/» Pointer to BASIC09 integer array •/ 

/* and it's size */ 

/• Pointer integer value (string length) •/ 

/• Size of integer •/ 

/* Pointer to integer (sort count) •/ 

/• Size of integer •/ 

The following assembly code loads Y with the first 

arg provided by BASIC09. This code MUST be the first code 

in the function after the declarations. This code assumes the 

address of the data area is the first parameter in the BASIC09 

RUN command. */ 

#asm 

ldy 6,s get addr for C data storage 
#endasm 

/* Use the C library qsort function to do the sort. Our 

own BASIC09 string compare function will compare the strings. 



int 


argent; 


char 


•stor; 


char 


iarray[ ] ; 


int 


iasize, 




•elemlen, 




elsiz ; 




•icount, 




icsiz ; 


{ 




/« The followi 



• 



/ 



} 



qsort (iarray, •icount , maxstr=*elemlen, strbemp) ; 



/• define stuff cstart.r normally defines «/ 
#asm 

_stkcheck: 
rts dummy stack check function 

vsect 
errno: rmb 2 C function system error number 
_flacc: rmb 8 C library float/long accumulator 

endsect 
tfendasm 

The BASIC09 calling program: (words file contains strings to sort) 

PROCEDURE ssorter 

DIM a(200) :STRING[20] 

DIM cmemory:STRING[20] 

DIM i,n:INTEGER 

DIM path: INTEGER 

OPEN #path,"words":READ 

n=100 

FOR i=1 TO n 

INPUT #path,a(i) 

NEXT i 

CLOSE #path 

RUN prin(a,n) 

RUN cssort (cmemory , a, 20 ,n) 
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RUN prin(a,n) 
END 

PROCEDURE prin 

PARAM a(100):STRING[20]; n:INTEGER 

DIM i: INTEGER 

FOR i=1 TO n 

PRINT i; " "; a(i) 

NEXT i 

PRINT 

END 

The next example shows how to access BASIC09 reals from C functions: 



flmult( cnt , cmemory , cmemsiz, realarg, real size) 

int cnt; /» number of arguments •/ 

char *cmemory; /» pointer to some memory for C use */ 

double »realarg; /• pointer a real •/ 

{ 

#asm 

ldy 6,s get static memory address 
#endasm 

double number; 

getbreal(&number, realarg) ; /« get the BASIC09 real »/ 
number *= 2.; /• number times twoV 

putbreal(realarg, &number) ; /* give back to BASIC09 */ 



/• getbreal(creal, breal) 

get a 5-byte real from BASIC09 format to C format */ 

getbreal(creal, breal) 
double *creal , *breal ; 
{ 

register char »cr,*br; /• setup some char pointers */ 

cr = creal; 
br = breal; 
#asm 

* At this point U reg contains address of C double 

* 0,s contains address of BASIC09 real 
ldx 0,s get address of B real 

clra clear the C double 

clrb 

std 0,u 

std 2,u 

std 4,u 

stb 6,u 

ldd 0,x 
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beq g3 BASIC09 real is zero 



ldd 1 ,x get hi B mantissa 
anda #$7f clear place for 
std 0,u put hi C mantissa 
ldd 3,x get lo B mantissa 
andb #$fe mask off sign 
std 2,u put lo C mantissa 
Ida 4,x get B sign byte 
lsra shift out sign 
bcc g1 

Ida 0,u get C sign byte 
ora #$80 turn on sign 
sta 0,u put C sign byte 

g1 Ida 0,x get B exponent 
suba #128 excess 128 
sta 7,u put C exponent 

g3 clra clear carry 

#endasm 



sign 



} 

/* putbreal(breal, creal) 

put C format double into a 5-byte real from BASIC09 •/ 

putbreal (breal , creal) 
double *breal, *creal; 
{ 

register char *cr,*br; /» setup some char pointers •/ 

cr = creal; 
br = breal; 
#asm 

* At this point U reg contains address of C double 

* 0,s contains address of BASIC09 real 
ldx 0,s get address of B real 

Ida 7,u get C exponent 

bne pO not zero? 

clra clear the BASIC09 

clrb real 

std 0,x 

std 2,x 

sta 4 , x 

bra p3 and exit 

pO ldd 0,u get hi C mantissa 
ora #$80 this bit always on for normalized real 
std 1,x put hi B mantissa 
ldd 2,u get lo C mantissa 
std 3,x put lo B mantissa 
incb round mantissa 
bne p1 
inc 3,x 
bne pi 
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inc 2,x 

bne p1 

inc 1 ,x 
p1 andb #$fe turn off sign 

stb 4,x put B sign byte 

Ida 0,u get C sign byte 

lsla shift out sign 

bee p2 bra if positive 

orb #$01 turn on sign 

stb 4,x put B sign byte 
p2 Ida 7,u get C exponent 

adda #128 less 128 

sta 0,x put B exponent 
P3 clra clear carry 
#endasm 
} 

/* replace cstart.r definitions for BASIC09 */ 
#asm 

_stkcheck: 
_stkchec : 
rts 

vsect 
_flacc: rmb 8 
errno: rmb 2 

endsect 
#endasm 

BASIC09 calling program: 

PROCEDURE btest 

DIM a:REAL 

DIM i: INTEGER 

DIM cmemory:STRING[32] 

a=1 . 

FOR i=1 TO 10 

RUN flmult(cmemory ,a) 

PRINT a 
NEXT i 
END 
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The last program is an example of accessing BASIC09 matrix elements. 
The C program: 



matmult(cnt , cmemory , cmemsiz , matxaddr ,matxsize, scalar , seal size) 

char *cmemory; /* pointer to some memory for C use •/ 

int matxaddr [5] [ 3] ; /* pointer a double dim integer array */ 

int •scalar; /* pointer to integer •/ 

{ 

#asm 

ldy 6,s get static memory address 
# end asm 

int i,j; 

for(i=0; i<5; ++i) 

for(j=1; j<3; ++j) 

matxaddr[ j] [i] »= "scalar; /• multiply by value 
*/ 
} 

#asm 

_stkcheck: 
_stkchec : 
rts 

vsect 
_flacc: rmb 8 
errno : rmb 2 

endsect 
#endasm 

BASIC09 calling program: 

PROCEDURE btest 
DIM im(5,3) :INTEGER 
DIM i,j: INTEGER 
DIM cmem:STRING[32] 
FOR i=1 TO 5 

FOR j=1 TO 3 

READ im(i,j) 

NEXT j 
NEXT i 

DATA 11, 13, 7, 3, 4, 0,5, 7, 2, 8, 15, 0,0, 14, 4 
FOR i=1 TO 5 

PRINT im(i,1 ) ,im(i,2) ,im(i,3) 
NEXT i 
PRINT 

RUN matmult( cmem, im,64) 
FOR i=1 TO 5 

PRINT im(i,1 ) ,im(i,2) ,im(i,3) 
NEXT i 
END 
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RELOCATING MACRO ASSEMBLER REFERENCE 

This appendix gives a summary of the operation of the "Relocating 
Macro Assembler" (named c.asm as distributed with the C Compiler). 
This appendix and the example assembly source files supplied with 
the C compiler should provide basic information on how to use the 
"Relocating Macro Assembler" to create relocatable-object format 
files (ROF). It is further assumed that you are familiar with the 
6809 instruction set and mnemonics. See the Microware Relocating 
Assembler Manual for a more detailed description. The main function 
of this appendix is to enable the reader to understand the output 
produced by c.asm. The Relocating Macro Assembler allows programs 
to be compiled separately and then linked together, and it also 
allows macros to be defined within programs. 

Differences between the Relocating Macro Assembler ( RMA) and the 
Microware Interactive Assembler (MIA ) : 

RMA is does not have an interactive mode. Only a disk file is 
allowed as input. 

RMA output is an ROF file. The ROF file must be processed by 
the linker to produce an executable 0S9 memory module. The 
layout of the ROF file is described later. 

RMA has a number of new directives to control the placement of 
code and data in the executable module. Since RMA does not 
produce memory modules, the MIA directives "mod" and "emod" are 
not present. Instead, new directives PSECT and VSECT control 
the allocation of code and data areas by the linker. 

RMA has no equivalent to the MIA "setdp" directive. Data (and 
DP) allocation is handled by the linker. 
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Symbolic Names. 

A symbolic name is valid if it consists of from one to nine 
uppercase or lowercase characters, decimal digits or the characters 
"$". "_", "." or "@". RMA does not fold lowercase letters to 
uppercase. The names "Hi. you" and "HI. YOU" are distinct names. 

Label field. 



If 



symbolic name in the label field of a source statement is 



followed by a ":" (colon), the name will be known GLOBALLY (by all 

modules linked together). If no colon appears, the name will be 

known only in the PSECT in which it was defined. PSECT will be 
described later. 



Undefined names. 

If a symbolic name is used in an expression and hasn't been defined, 
RMA assumes the name is external to the PSECT. RMA will record 
information about the reference so the linker can adjust the operand 
accordingly. External names cannot appear in operand expressions 
for assembler directives. 



Listing format. 

00098 0032 59 
00117 0045=17ffb8 



label 



rolb 
lbsr 



dmove 



Comment 



| | | | Start of comment 

| | | Start of operand 
| | Start of mnemonic 
! Start of label 

A "+" indicates a line generated by a macro 
expansion. 
Start of object code bytes. 
An "=" here indicates that the operand contains an 
external reference. 
Location counter value. 
Line number. 



Section location counters. 

Each section contains the following location counters: 



PSECT 
VSECT 



CSECT 



instruction location counter 
initialized direct page location counter 
non-initialized direct page location counter 
initialized data location counter 
non-initialized data location counter 
base offset counter 



Section directives. 



RMA contains 3 
the beginning 



section directives. PSECT indicates to the linker 
of a relocatable-object-format file(ROF) and 
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initializes the instruction and data location counters and assembles 
code into the ROF object code area. VSECT causes RMA to change to 
the data location counters and place any generated code into the 
appropriate ROF data area. CSECT initializes a base value for 
assigning offsets to symbols. The end of these sections is 
indicated by the ENDSECT directive. 

The source statements placed in a particular section cause the 

linker to perform a function appropriate for the statement. 

Therefore, the mnemonics allowed within a section are restricted as 
follows : 

These mnemonics are allowed inside or outside any section: nam, 

opt, ttl, pag, spc, use, fail, rept, endr, ifeq, ifne, iflt, 

ifle, ifge, ifgt, ifpl , endc, else, equ, set, macro, endm, 
csect, and endsect. 

Within a CSECT: rmb . 

Within a PSECT: any 6809 instruction mnemonic, fee, fdb, fes, 
fob, rzb, vsect, endsect, os9 and end. 

Within a VSECT: rmb, fee, fdb, fes, fob, rzb and endsect. 

PSECT directive. 

The main difference between PSECT and MOD is that MOD set up 
information for 0S-9 and PSECT sets up information for the 
linker(c. link in the C compiler). 

PSECT {name, typelang, at tr rev, edition, stacksize, entrypoint} 

name Up to 20 bytes (any printable character except space 
or comma) for a name to be used by the linker to 
identify this PSECT. This name need not be distinct 
from all other PSECTs linked together, but it helps 
to identify PSECTs the linker has a problem with if 
the names are different. 

typelang byte expression for the executable module type/lang- 
uage byte. If this PSECT is not a "mainline" (a 
module that has been designed to be forked to) mod- 
ule this byte must be zero. 

attrrev byte expression for executable module attribute/rev- 
ision byte. 

edition byte expression for executable module edition byte. 

stacksize word expression estimating the amount of stack stor- 
age required by this psect. The linker totals this 
value in all PSECTs to appear in the executable mod- 
ule and adds this value to any data storage require- 
ment for the entire program. 



Page D-3 



MICROWARE C COMPILER USER'S GUIDE 
APPENDIX D 



entrypoint word expression entrypoint offset for this PSECT. 
If the PSECT is not a mainline module, this should 
be set to zero. 



PSECT must have either no operand list or an operand list containing 
a name and five expressions. If no operand list is provided, the 
PSECT name defaults to "program" and all other expressions to zero. 
There can only be one PSECT per assembly language file. 



The PSECT directive initializes all counter orgs and marks the start 
of the program module. No VSECT data reservations or object code 
may appear before or after the PSECT/ENDSECT block. 

Example: 

psect myprog, Prgrm+Objct, Reent+1 ,Edit ,0 , progent 
psect another__prog ,0 ,0 ,0 ,0 ,0 

VSECT directive. 

VSECT {DP} 

The VSECT directive causes RMA to change to the data location 
counters. If DP appears after VSECT, the direct page counters are 
used, otherwise the non-direct page data is used. The RMB directive 
within this section reserves the specified number of bytes in the 
appropriate uninitialized data section. The fee, fdb, fes, feb and 
rzb (reserve zeroed bytes) directives place data into the 
appropriate initialized data section. If an operand for fdb or feb 
contains an external reference, this information is placed in the 
external reference part of the R0F to be adjusted at link or 
execution time. ENDSECT marks the end of the VSECT block. Any 
number of VSECT blocks can appear within a PSECT. Note, however, 
that the data location counters maintain their values between one 
VSECT block and the next. Since the linker handles the actual data 
allocation, there is no facility provided to adjust the data 
location counters. 

CSECT directive. 

CSECT {expression} 

The CSECT directive provides a means for assigning consecutive 
offsets to labels without resorting to EQUs. If the expression is 
present, the CSECT base counter is set to that value, otherwise it 
is set to zero. 



RZB statement. 

Syntax: RZB <expression> 

The reserve zeroed bytes pseudo-instruction generates sequences of 
zero bytes in the code or initialized data sections, the number of 
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which is specified by the expression. 



COMPARISON BETWEEN ASSEMBLY PROGRAMS FOR THE MICROWARE INTERACTIVE 
ASSEMBLER AND THE RELOCATING MACRO ASSEMBLER 



The following two program examples simply fork BASIC09. The purpose 
of the examples are to show some of the differences in the new 
relocating assembler. The differences are apparent. 



« this 


P 


rogram forks basic09 
ifpl 

use . . . . /def s/os9def s. a 
endc 


PRGRM 




equ $10 


OBJCT 




equ $01 



stk equ 200 

psect rmatest ,$11 ,$81 ,0, stk, en try 



name 


fcs /basic09/ 


prm 


fcb $D 


prmsize 


equ *-prm 


entry 


leax name, per 




leau prm, per 




ldy #prmsize 




Ida #PRGRM+OBJCT 




clrb 




os9 F$F0RK 




os9 F$WAIT 




os9 F$EXIT 




endsect 



MACRO INTERACTIVE ASSEMBLER SOURCE 

ifpl 

use defsfile 

endc 

mod siz , prnam, type , revs, start , size 
prnam fcs /testshell/ 
type set prgrm+objet 
revs set reent+1 





rmb 


250 




rmb 


200 


name 


fcs 


/basic09/ 


prm 


$D 




prmsize 


equ 


»-prm (c 
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size 


equ . 


start 


equ » 




leax name, per 




leau prm,pcr 




ldy #prmsize 




Ida #PRGRM+OBJCT 




clrb 




os9 F$FORK 




os9 F$WAIT 




osg F$EXIT 




emod 


siz 


equ 
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MACROS 



Sometimes identical or similar sequences of instructions may be 

repeated in different places in a program. The problem is that if 

the sequence of instructions is long or must be used a number of 
times, writing it repeatedly can be tedious. 

A macro is a definition of an instruction sequence that can be 
used numerous places within a program. The macro is given a name 
which is used similarly to any other instruction mnemonic. Whenever 
RMA encounters the name of a macro in the instruction field, it 
outputs all the instructions given in the macro definition. In 
effect, macros allow the programmer to create "new" machine language 
instructions . 

For example, suppose a program frequently must perform 16 bit 
left shifts of the D register. The two instruction sequence can be 
defined as a macro, for example: 



dasl 



macro 
aslb 
rola 
endm 



The "macro" and "endm" directives specify the beginning and the 
end of the macro definition, respectively. The label of the "macro" 
directive specifies the name of the macro, "dasl" in this example. 
Now the "new" instruction can be used in the program: 



ldd 12, s 
dasl 
std 12, s 



get operand 
double it 
save operand 



In the example above, when RMA encountered the "dasl" macro, it 
actually outputted code for "aslb" and "rola". Normally, only the 
macro name is listed as above, but an RMA option can be used to 
cause all instructions of the "macro expansion" to be listed. 



Macros should not be confu 
are similar in some ways. Ma 
line" code sequence every time 
alteration of the instruction ope 
once, never change, and are calle 
JSR, and RTS). In those 
interchangeably, macros usually 
programs, and subroutines prod 
programs. Short macros (up to 6 
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MACRO STRUCTURE 



A macro definition consists of three sections: 

1 . The macro header - assigns a name to the macro 

2. The body - contains the macro statements 

3. The terminator - indicates the end of the macro 



<name> MACRO /* macro header */ 
body /* macro body */ 
ENDM /* macro terminator «/ 



The macro name must be defined by the label given in the MACRO 
statement. The name can be any legal assembler label. It is 
possible to redefine the 6809 instructions (LDA, CLR, etc.) 
themselves by defining macros having identical names. Caution: 
redefinition of assembler directives such as "RMB" can have 
unpredictable consequences. 

The body of the macro can contain any number of legal RMA 
instruction or directive statements including references to 
previously defined macros. The last statement of a macro definition 
must be ENDM. 

The text of macro definitions are stored on a temporary file 
that is created and maintained by RMA. This file has a large (1K 
byte) buffer to minimize disk accesses. Therefore, programs that 
use more than 1K of macro storage space should be arranged so that 
short, frequently used macros are defined first so they are kept in 
the memory buffer instead of disk space. 

Macro calls may be nested, that is, the body of a macro 
definition may contain a call to another macro. For example: 

times4 MACRO 
dasl 
dasl 
ENDM 

The macro above consists of the "dasl" macro used twice. The 
definition of a new macro within another is not permitted. Macro 
calls may be nested up to eight deep. 



D-8 



MICROWARE C COMPILER USER'S GUIDE 
APPENDIX D 



MACRO ARGUMENTS 



Arguments permit variations in the expansion of a macro. 
Arguments can be used to specify operands, register names, 
constants, variables, etc., in each occurence of a macro. 

A macro can have up to nine formal arguments in the operand 
fields. Each argument consists of a backslash character and the 
sequence number of the formal argument, e.g, \1 , \2 ... \9. When 
the macro is expanded, each formal argument is replaced by the 
corresponding text string "actual argument" given in the macro call. 
Arguments can be used in any part of the operand field not in the 
instruction or label fields. Formal arguments can be used in any 
order and any number of times. 

For example, the macro below performs the typical instruction 
sequence to create an OS-9 file: 



create 



MACRO 

leax \1 ,pcr 

Ida #\2 

ldb #\3 

os9 I$CREATE 

ENDM 



get addr of file name string 

set path number 

set file access modes 



This macro uses three arguments: "\1" for the file name string 
address; "\2" for the path number; and "\3" for the file access mode 
code. When "create" is referenced, each argument is replaced by the 
corresponding string given in the macro call, for example: 

create outname,2 , $1E 

The macro call above will be expanded to the code sequence: 

leax outname,pcr 

Ida #22 

ldb #$1E 

os9 I$CREATE 

If an argument string includes special characters such as 
backslashes or commas, the string must be enclosed in double quotes. 
For example, this macro reference has two arguments: 

double count, "2, s" 

An argument may be declared null by omitting all or some 
arguments in the macro call to make the corresponding argument an 
empty string so no substitution occurs when it is referenced. 
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There are two special argument operators that can be useful in 
constructing more complex macros. They are: 



\Ln - Returns the length of the actual 
argument n, in bytes. 

\# - Returns the number of actual arguments 
passed in a given macro call. 

These special operators are most commonly used in conjunction with 
RMA's conditional assembly facilities to test the validity of 
arguments used in a macro call, or to change the way a macro works 
according to the actual arguments used. When macros are performing 
error checking they can report errors using the FAIL directive. 
Here is an example using the "create" macro given on the previous 
page but expanded for error checking: 

create MACRO 

ifne \# - 3 must have exactly 3 args 

FAIL create: must have three arguments 

endc 

ifgt \L1 - 29 file name can be 1 - 29 chars 

FAIL create: file name too long 

endc 

leax \1,pcr get addr of file name string 

Ida #\2 set path number 

ldb #\3 set file access modes 

os9 I$CREATE 

ENDM 
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MACRO AUTOMATIC INTERNAL LABELS 



Sometimes it is necessary to use labels within a macro. Labels 
are specified by "\@ n . Each time the macro is called, a unique 
label will be generated to avoid multiple definition errors. Within 
the expanded code "\§" will take on the form "§xxx n , where xxx will 
be a decimal number between 000 to 999. 

More than one label may be specified in a macro by the addition 
of an extra character ( s) . For example, if two different labels are 
required in a macro, they can be specified by "\@A n and "ygB". In 
the first expansion of the macro, the labels would be n @001A" and 
n @001B n , and in the second expansion they would be ''@002A I, and 
"002B". The extra characters may be appended before the n \" or 
after the "@". 

Here is an example of macro that uses internal labels: 

testovr MACRO 





cmpd 


#\1 


compare to arg 




bis 


\§A 


bra if in range 




orcc 


#1 


set carry bit 




bra 


\@B 


and skip next instr 


\eA 


andcc 


#$FE 


clear carry 


\§B 


equ 


• 


continue. . . 



Suppose the first macro call is: 

testovr $80 
The expansion will be: 





cmpd 


#$80 




bis 


@001A 




orcc 


#1 




bra 


§001B 


@001A 


andcc 


#$FE 


@001B 


equ 


* 



compare to arg 
bra if in range 
set carry bit 
and skip next instr. 
clear carry 
continue. . . 



If the second macro call is: 

testovr 240 
The expansion will be: 





cmpd 


#240 


compare to arg 




bis 


@002A 


bra if in range 




orcc 


#1 


set carry bit 




bra 


@002B 


and skip next instr 


@002A 


andcc 


#$FE 


clear carry 


@002B 


equ 


* 


continue. . . 



D-11 



MICROWARE C COMPILER USER'S GUIDE 
APPENDIX D 



ADDITIONAL COMMENTS ABOUT MACROS 



Macros can be an important and useful programming tool that can 
significantly extend RMA's capabilities. In addition to creating 
instruction sequences, they can also be used to create complex 
constant tables and data structures. 

Macros can also be dangerous in the sense that if they are used 
indiscriminately and unnecessarily they can impair the readability 
of a program and make it difficult for programmers other than the 
original author to understand the program logic. Therefore, when 
macros are used they should be carefully documented. 
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TERMS AND CONDITIONS OF SALE AND LICENSE OF RADIO SHACK 
COMPUTER EQUIPMENT AND SOFTWARE PURCHASED FROM A 
RADIO SHACK COMPANY-OWNED COMPUTER CENTER, RETAIL 

STORE OR FROM A RADIO SHACK FRANCHISEE OR DEALER AT ITS 
AUTHORIZED LOCATION 



CUSTOMER OBLIGATIONS 



LIMITED WARRANTY 
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A. CUSTOMER assumes full responsibility that this Radio Shack computer hardware purchased (the 
"Equipment"), and any copies of Radio Shack software included with the Equipment or licensed 
separately (the "Software") meets the specifications, capacity, capabilities, versatility, and other 
requirements of CUSTOMER. 

B. CUSTOMER assumes full responsibility for the condition and effectiveness of the operating 
environment in which the Equipment and Software are to function, and for its installation. 

II. RADIO SHACK LIMITED WARRANTIES AND CONDITIONS OF SALE 

A. For a period of ninety (90) calendar days from the date of the Radio Shack sales document 
received upon purchase of the Equipment, RADIO SHACK warrants to the original CUSTOMER that 
the Equipment and the medium upon which the Software is stored is free from manufacturing 
defects. THIS WARRANTY IS ONLY APPLICABLE TO PURCHASES OF RADIO SHACK EQUIPMENT 
BY THE ORIGINAL CUSTOMER FROM RADIO SHACK COMPANY-OWNED COMPUTER CENTERS, 
RETAIL STORES AND FROM RADIO SHACK FRANCHISEES AND DEALERS AT ITS AUTHORIZED 
LOCATION. The warranty is void if the Equipment's case or cabinet has been opened, or if the 
Equipment or Software has been subjected to improper or abnormal use. If a manufacturing defect 
is discovered during the stated warranty period, the defective Equipment must be returned to a 
Radio Shack Computer Center, a Radio Shack retail store, participating Radio Shack franchisee or 
Radio Shack dealer for repair, along with a copy of the sales document or lease agreement. The 
original CUSTOMER'S sole and exclusive remedy in the event of a defect is limited to the 
correction of the defect by repair, replacement, or refund of the purchase price, at RADIO 
SHACK'S election and sole expense. RADIO SHACK has no obligation to replace or repair 
expendable items. 

B. RADIO SHACK makes no warranty as to the design, capability, capacity, or suitability for use of 
the Software, except as provided in this paragraph. Software is licensed on an "AS IS" basis, 
without warranty. The original CUSTOMER'S exclusive remedy, in the event of a Software 
manufacturing defect, is its repair or replacement within thirty (30) calendar days of the date of the 
Radio Shack sales document received upon license of the Software. The defective Software shall 
be returned to a Radio Shack Computer Center, a Radio Shack retail store, participating Radio 
Shack franchisee or Radio Shack dealer along with the sales document. 

C. Except as provided herein no employee, agent, franchisee, dealer or other person is authorized to 
give any warranties of any nature on behalf of RADIO SHACK. 

D. Except as provided herein, RADIO SHACK MAKES NO WARRANTIES, INCLUDING WARRANTIES 
OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 

E. Some states do not allow limitations on how long an implied warranty lasts, so the above 
limitation(s) may not apply to CUSTOMER. 

III. LIMITATION OF LIABILITY 

A. EXCEPT AS PROVIDED HEREIN, RADIO SHACK SHALL HAVE NO LIABILITY OR RESPONSIBILITY 
TO CUSTOMER OR ANY OTHER PERSON OR ENTITY WITH RESPECT TO ANY LIABILITY, LOSS 
OR DAMAGE CAUSED OR ALLEGED TO BE CAUSED DIRECTLY OR INDIRECTLY BY 
"EQUIPMENT" OR "SOFTWARE" SOLD, LEASED, LICENSED OR FURNISHED BY RADIO SHACK, 
INCLUDING, BUT NOT LIMITED TO, ANY INTERRUPTION OF SERVICE, LOSS OF BUSINESS OR 
ANTICIPATORY PROFITS OR CONSEQUENTIAL DAMAGES RESULTING FROM THE USE OR 
OPERATION OF THE "EQUIPMENT" OR "SOFTWARE". IN NO EVENT SHALL RADIO SHACK BE 
LIABLE FOR LOSS OF PROFITS, OR ANY INDIRECT, SPECIAL, OR CONSEQUENTIAL DAMAGES 
ARISING OUT OF ANY BREACH OF THIS WARRANTY OR IN ANY MANNER ARISING OUT OF OR 
CONNECTED WITH THE SALE, LEASE, LICENSE, USE OR ANTICIPATED USE OF THE "EQUIPMENT" 
OR "SOFTWARE". 

continued 
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NOTWITHSTANDING THE ABOVE LIMITATIONS AND WARRANTIES, RADIO SHACK'S LIABILITY 
HEREUNDER FOR DAMAGES INCURRED BY CUSTOMER OR OTHERS SHALL NOT EXCEED THE 
AMOUNT PAID BY CUSTOMER FOR THE PARTICULAR "EQUIPMENT" OR "SOFTWARE" 
INVOLVED. 

B. RADIO SHACK shall not be liable for any damages caused by delay in delivering or furnishing 
Equipment and/or Software. 

C. No action arising out of any claimed breach of this Warranty or transactions under this Warranty 
may be brought more than two (2) years after the cause of action has accrued or more than four 
(4) years after the date of the Radio Shack sales document for the Equipment or Software, 
whichever first occurs. 

D. Some states do not allow the limitation or exclusion of incidental or consequential damages, so the 
above limitation(s) or exclusion(s) may not apply to CUSTOMER. 

IV. RADIO SHACK SOFTWARE LICENSE 

RADIO SHACK grants to CUSTOMER a non-exclusive, paid-up license to use the RADIO SHACK Software 
on one computer, subject to the following provisions: 

A. Except as otherwise provided in this Software License, applicable copyright laws shall apply to the 
Software. 

B. Title to the medium on which the Software is recorded (cassette and/or diskette) or stored (ROM) 
is transferred to CUSTOMER, but not title to the Software. 

C. CUSTOMER may use Software on one host computer and access that Software through one or 
more terminals if the Software permits this function. 

D. CUSTOMER shall not use, make, manufacture, or reproduce copies of Software except for use on 
one computer and as is specifically provided in this Software License. Customer is expressly 
prohibited from disassembling the Software. 

E. CUSTOMER is permitted to make additional copies of the Software only for backup or archival 
purposes or if additional copies are required in the operation of one computer with the Software, 
but only to the extent the Software allows a backup copy to be made. However, for TRSDOS 
Software, CUSTOMER is permitted to make a limited number of additional copies for 
CUSTOMER'S own use. 

F. CUSTOMER may resell or distribute unmodified copies of the Software provided CUSTOMER has 
purchased one copy of the Software for each one sold or distributed. The provisions of this 
Software License shall also be applicable to third parties receiving copies of the Software from 
CUSTOMER. 

G. All copyright notices shall be retained on all copies of the Software. 

V. APPLICABILITY OF WARRANTY 

A. The terms and conditions of this Warranty are applicable as between RADIO SHACK and 
CUSTOMER to either a sale of the Equipment and/or Software License to CUSTOMER or to a 
transaction whereby RADIO SHACK sells or conveys such Equipment to a third party for lease to 
CUSTOMER. 

B. The limitations of liability and Warranty provisions herein shall inure to the benefit of RADIO 
SHACK, the author, owner and/or licensor of the Software and any manufacturer of the Equipment 
sold by RADIO SHACK. 

VI. STATE LAW RIGHTS 

The warranties granted herein give the original CUSTOMER specific legal rights, and the original 
CUSTOMER may have other rights which vary from state to state. 
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